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

The description adds valuable behavioral details beyond the annotations: the 'private' alias maps to 'restricted' on the wire, unscoped packages are always public, and restricted access requires a paid account. These complement the readOnlyHint/destructiveHint annotations without contradicting them.

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?

The description is concise and front-loaded with the primary action. Each sentence adds important context: purpose, alias mapping, scoping constraint, and account requirement. No wasted words or redundancy.

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 simple two-parameter tool with no output schema, the description covers the essential context: allowed values, alias behavior, limitations (unscoped packages), and prerequisites (paid account for restricted). It could mention authentication requirements or the impact on existing package visibility, but these are minor gaps.

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 already describes both parameters with 100% coverage, but the description adds extra meaning: it clarifies the alias behavior of 'private' for the access parameter and explains that name's scoping affects the outcome (unscoped packages are always public). This goes beyond the schema descriptions.

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 the tool's purpose: 'Set package access level' with specific allowed values ('public' or 'restricted'). It distinguishes from siblings like npm_package_access (likely for viewing) and npm_access_set_mfa by focusing on the access level setting action.

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 description provides clear context for when to use the tool: it works on scoped packages (unscoped are always public) and restricted access requires a paid account. However, it does not explicitly mention alternative tools or state 'when not to use' scenarios.

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

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

Annotations already indicate this is a write operation with destructive potential. The description adds value by explaining the meaning of each level, but it does not disclose consequences such as impact on current users or the need for elevated permissions. It provides adequate but not rich behavioral context.

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?

The description is a single, front-loaded sentence that efficiently explains the tool's purpose and all configuration values. No word is wasted, and the clarity remains high.

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 the tool's simplicity (2 parameters, no output schema), the description covers the critical semantics of the configuration levels. It lacks explicit statements about post-change effects or prerequisites, but annotations mitigate the destructiveness. Overall, it is sufficient for an agent to invoke the tool correctly.

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?

While the schema already includes descriptions for both parameters, the description enriches the 'level' enum by clarifying that 'none' means off, 'publish' requires 2FA, and 'automation' allows automation tokens to bypass. This adds practical meaning beyond the bare schema.

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 the tool configures 2FA requirements for publishing and enumerates the three possible levels with brief explanations. This is a specific verb+resource and distinguishes it from other npm tools, though it does not explicitly differentiate from the similar sibling npm_access_set.

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 description provides no guidance on when to use this tool versus alternatives like npm_access_set or how changes affect existing workflows. It only describes the configuration options without contextualizing their appropriate use.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive. The description adds valuable behavioral context by specifying the return payload (severity, CVEs, patched versions) and the nature of the call ('bulk advisory API'), which goes beyond the structured annotations without contradicting them.

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 sentences deliver purpose, scope, return values, and an alternative tool reference. Every word earns its place; no fluff or repetition. The alternative guidance is front-loaded and the description is perfectly sized for a single-parameter read-only tool.

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?

The tool has one required parameter, a comprehensive schema, strong annotations, and no output schema. The description covers what the tool does, what it returns, and when to use a different tool. It is complete for the tool's complexity; no further context is necessary.

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 description covers 100% of the parameter with a clear example and structure. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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 opens with a specific verb phrase 'Quick vulnerability check for specific packages and versions' and identifies the resource (npm package advisories via bulk API). It explicitly differentiates from the sibling npm_audit_deep by stating what this tool returns and pointing to the deeper variant for richer detail.

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 description clearly states when to use this tool: for quick vulnerability checks returning severity, CVEs, and patched versions. It explicitly recommends npm_audit_deep when richer detail is needed, providing an unambiguous alternative and usage boundary.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing the specific endpoint (npm audit v1) and the richer detail level, which are behavioral traits not captured in annotations. No contradiction exists.

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 sentences, front-loaded with the core purpose, then alternative and prerequisite. Every word earns its place; no filler or repetition.

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 no output schema, the description compensates by enumerating return contents (CVSS scores, CWEs, affected version ranges, fix recommendations, full vulnerability metadata). It also covers prerequisite and alternative. Together with strong annotations, it is nearly complete, though it could mention potential latency or auth requirements.

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 input schema covers all parameters with descriptions (100% coverage), so the schema does the heavy lifting. The description adds the semantic hint that the dependency map should come from npm_dependencies, but this is a usage note rather than a deeper semantic definition of the parameters themselves.

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 states a specific verb and resource: 'Full security audit on a dependency set' and explicitly compares itself to npm_audit by noting it uses the npm audit v1 endpoint for 'richer detail'. This clearly differentiates it from the sibling tool.

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 an explicit prerequisite: 'use npm_dependencies to get it first' and names the alternative npm_audit, implying when to choose this tool for richer detail. It does not explicitly list when-not-to-use cases, but the comparison and prerequisite provide strong guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond this: it returns a canPublishHeadless boolean and a recommendation, detects headless limitations, and provides the exact terminal command for a human to run. It also explains the MCP server constraint (cannot open browsers), which is critical for agents.

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?

The description is concise yet complete: two short paragraphs, first sentence front-loads the purpose, subsequent sentences add necessary behavior and usage context. Every sentence earns its place with no redundancy or fluff.

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 zero-parameter read-only health check, the description fully covers what it does, when to use it, what it returns (structured data, canPublishHeadless boolean, recommendation, terminal command), and why it exists (AI limitations). This is complete given the absence of an output schema.

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 tool has zero parameters, so the schema provides no semantics to add. The description correctly focuses on outputs rather than inputs. The baseline for 0 params is 4, and the description doesn't miss any parameter-related information.

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 a 'Quick auth health check' that returns structured data about npm auth status, token capability, and headless publishing possibility. This specific verb+resource framing distinguishes it from siblings like npm_whoami (identity only) and npm_verify_token (token verification) by focusing on pre-publish headless capability.

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?

Explicitly instructs 'Run this BEFORE attempting any publish operation' and explains why (AI cannot open browsers/enter OTP codes, provides terminal command for human). This is clear context, though it doesn't name specific alternative tools for 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the behavior of returning permission levels, but does not provide deeper context like auth requirements or pagination. With annotations present, this is adequate but not rich.

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?

The description is two sentences, front-loaded with the primary purpose and followed by a practical use case. Every sentence earns its place with no redundant wording.

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 the low complexity (single parameter, no output schema) and strong annotations, the description is sufficient. It states what is returned (users and permission levels) and provides a practical scenario. Minor gaps like pagination or response format are not critical for this simple read operation.

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 input schema has 100% coverage with a single parameter 'name' and a clear description with examples. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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 the tool's function: 'Get all users who have access to a package and their permission levels (read-only, read-write).' This uses a specific verb and resource, and distinguishes it from siblings like npm_maintainers or npm_package_access by focusing on collaborators and permission levels.

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 description provides a clear use case: 'Useful for verifying who can publish to a package before setting up CI/CD.' However, it does not explicitly mention alternatives or when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safe nature is known. The description adds that it returns comparison data across specific metrics, but does not disclose response format, error behavior, or rate limits. It aligns with annotations and adds some context, but no hidden behavioral traits are revealed.

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?

The description is two sentences, front-loaded with the core action and scope. Every phrase adds value, and there is no filler or redundant information beyond the acceptable repetition of the package count.

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 simple read-only comparison tool with one parameter, the description covers purpose, use case, and output content by listing the comparison dimensions. It is complete enough without an output schema, given the tool's simplicity and the strong annotation coverage.

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 covers 100% of the parameter with a clear description of the 'packages' array, including min/max bounds. The description reiterates the 2-5 range but adds no additional details about package name formats or invalid input behavior. With high schema coverage, a baseline score of 3 is appropriate.

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 uses the specific verb 'Compare' with an explicit scope of 2-5 packages and lists the comparison dimensions (downloads, version, license, etc.). This clearly distinguishes it from sibling tools like npm_package or npm_search, which focus on single packages or searching.

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 explicitly states it is 'Great for should I use X or Y? decisions,' which conveys a primary use case. It does not name alternative tools or when not to use it, but the side-by-side framing implicitly differentiates it from single-package tools. This is clear enough without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the agent knows this is a safe read operation. The description adds useful context about the specific dependency categories returned, but does not disclose any additional behavioral traits such as pagination, rate limits, or error handling. This aligns with the baseline for descriptions that benefit from strong annotations.

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?

The description is a single, front-loaded sentence that immediately states the core action and then enumerates the dependency categories. Every word contributes value, and there is no redundancy or extraneous detail.

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?

This is a simple read-only tool with 2 parameters, no output schema, and no nested objects. The description adequately conveys the purpose and return type (dependency lists). While it does not detail the exact response structure, the simplicity of the tool and the strong annotations make the description sufficiently complete for an agent to select and invoke it correctly.

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% with clear parameter descriptions: 'name' (Package name) and 'version' (Semver version or dist-tag, default 'latest'). The description does not add further meaning beyond the schema, but it does reinforce that the tool operates on a specific version, which is consistent with the parameters. Baseline 3 is appropriate since the schema handles parameter documentation.

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 the verb ('Get') and the resource ('dependency lists for a specific package version'), explicitly enumerating the dependency types (production deps, devDeps, peerDeps, optionalDeps). This distinguishes it from sibling tools like npm_dep_tree or npm_package, which likely serve different purposes.

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 description provides no guidance on when to use this tool versus alternatives such as npm_dep_tree or npm_package. There is no mention of exclusions, prerequisites, or situations where another tool would be more appropriate. The intended use is only implied by the tool's purpose.

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

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

Even with annotations already marking destructive and idempotent behavior, the description adds a lot: token authentication with 401/403 on missing 2FA bypass, a 1024-character registry limit, local HTTP 400 before any write when the message is too long or versionRange matches nothing, and 422 from the registry describing the sent packument. This is instructive and consistent with the annotations.

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, front-loaded with the core action and effect. The rest adds behavioral and error-manager detail that mostly earns its place; 'Message punctuation is never checked' is mildly odd but acceptable as an edge-case disclosure. No real bloat.

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 a write operation with no output schema, the description covers the essential elements: auth mechanism, side effect, hard limits, pre-write validation, and error statuses. An agent can successfully invoke the tool and understand common failure modes without needing additional documentation.

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 schema already explains name, message, versionRange semantics ('Omit to deprecate ALL versions', 'Use npm_undeprecate to clear', x-range semantics). The description only adds message-length/error semantics indirectly, not a substantive semantic expansion of 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 first sentence 'Deprecate a package or specific versions' gives a specific verb and resource, and adds the effect 'Shows a warning message on install'. It does not explicitly name or contrast with sibling tools like npm_undeprecate, so it is clear but not top-tier on sibling differentiation.

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 description implies a usage path by saying 'Uses the HTTP API with NPM_TOKEN, so no CLI login or OTP prompt is involved', which hints at when to choose this approach. However, there is no explicit when-to-use versus when-not-to-use guidance and no named alternatives in the description itself.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing rate-limit behavior ('10 in flight'), performance expectations ('wide tree at depth 4-5 can take a while'), a hard time cap ('60s'), and the truncated result flag with warning. This is exactly the kind of behavioral detail an agent needs to anticipate long-running or incomplete calls.

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 sentences deliver the core purpose and a critical performance caveat in a compact, front-loaded manner. Every clause earns its place: what the tool does, how it behaves, and what to expect on timeout. No filler or redundancy.

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 the absence of an output schema, the description still explains the main return signal ('truncated: true') and warns about timeouts. It covers the essential operational context (registry requests, concurrency, depth limits) so an agent can decide whether to invoke it and how to set depth. No critical missing context for calling this tool.

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 input schema already documents all three parameters comprehensively (name, depth, version), achieving 100% coverage. The description adds minimal new parameter meaning beyond the schema, only reiterating depth as configurable and mentioning the root-counting convention that is already in the schema. Baseline 3 applies.

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 the verb ('Resolve') and the exact resource ('production dependency tree for a package version'), and explicitly mentions the output ('full transitive dependency graph with versions'). It distinguishes itself from many sibling npm tools by focusing on the recursive tree structure rather than a single package or metadata lookup.

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 description implies when to use it (when a transitive dependency tree is needed) but does not explicitly state when not to use it or which sibling tool is an alternative (e.g., npm_dependencies for a flat list). It gives context about depth limits and performance trade-offs, but no explicit exclusion guidance.

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

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

Annotations already indicate write/destructive characteristics, and the description adds a valuable behavioral nuance about the 'latest' tag restriction. It also implies idempotency by not mentioning any error conditions, consistent with the idempotentHint. The description complements rather than repeats the annotations.

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?

The description is two concise sentences, front-loaded with the core action and followed by a key constraint. Every word earns its place; there is no redundancy or irrelevant detail.

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 simple two-parameter tool with no output schema, the description provides sufficient context. The destructive nature is declared via annotations, and the 'latest' exception is highlighted. It could mention expected result or reversibility, but given the annotations cover the safety profile, the description is reasonably complete.

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% for both parameters (tag and name), so the description doesn't need to add parameter details. It adds minimal extra meaning beyond the schema, which is acceptable given the schema already fully describes 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 the action ('Remove a dist-tag from a package') with a specific verb and resource. It also distinguishes this from related tools like npm_dist_tag_set by indicating it is the removal counterpart, and the note about 'latest' adds unambiguous scope.

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 description clearly defines when to use the tool (when you want to delete a dist-tag) and includes an important exclusion (the 'latest' tag cannot be removed, only reassigned). It doesn't explicitly name alternative tools like npm_dist_tag_set, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds examples of dist-tags but does not disclose return format, error behavior, or any rate limits. It does not contradict annotations.

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?

The description is a single concise sentence that front-loads the action (Get dist-tags) and adds clarifying examples. No unnecessary words or repetition.

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 simple read-only tool with one parameter, the description is mostly complete. It does not explicitly describe the return format (e.g., a map of tag to version), but the examples of tags make the expected output reasonably clear. Minor gap given no output schema.

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% with the parameter 'name' described as 'Package name'. The description only repeats 'package' without adding format or constraints, so it does not exceed the baseline provided by the schema.

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 uses a specific verb ('Get') with a clear resource ('dist-tags for a package') and provides illustrative examples ('latest, next, beta, etc.'). It clearly distinguishes from write siblings like npm_dist_tag_set and npm_dist_tag_remove.

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 description implies the tool is for retrieving dist-tags but does not explicitly state when to use it over alternatives such as npm_versions or npm_package. It lacks any when-to-use or when-not-to-use guidance, though the purpose itself is clear enough for basic selection.

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

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

Annotations already disclose that this is a write operation (readOnlyHint=false), destructive (destructiveHint=true), and idempotent (idempotentHint=true). The description adds common use cases but does not disclose additional behavioral traits such as permission requirements or the fact that the previous tag association is overwritten. This is adequate but not rich, given the annotation coverage.

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?

The description is two sentences, front-loaded with the action, and every sentence adds value. It avoids filler and is highly efficient.

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 simple three-parameter tool with no output schema, the description is complete enough. It covers the purpose, use cases, and examples, while annotations and schema handle the safety and parameter details. A slight gap is the lack of mention of overwriting behavior, but that is not critical for a tool of this simplicity.

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% for all three parameters (tag, name, version), so the descriptions already carry the semantic burden. The tool description provides some extra flavor with tag examples ('latest', 'beta', 'next') but adds no substantive information beyond the schema.

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 the tool's action: 'Point a dist-tag ... at a specific version.' It uses a specific verb ('point') and identifies the resource and target, with examples ('latest', 'beta', 'next') that distinguish it from sibling tools like npm_dist_tags (list) and npm_dist_tag_remove.

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 description provides clear context for when to use the tool via 'Common uses: promote a beta to latest, roll back latest to a prior version, maintain separate channels.' However, it does not explicitly name alternatives or state when not to use it, so it falls short of the highest score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read operation. The description adds value by specifying the accepted period formats including custom date ranges, which is behavioral context beyond the annotations. It does not describe error handling or response structure, but the annotations lower the bar.

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?

The description is a single, well-structured sentence that front-loads the primary action and then provides the period options in parentheses. Every word is informative with no redundancy or fluff.

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?

The tool is simple with two parameters and strong annotations, so the description covers the essential purpose and period options. It does not state the return format, but 'total download count' reasonably implies a numeric result. The lack of a return format description is a minor gap in an otherwise complete description for this tool's complexity.

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 schema already documents the 'name' and 'period' parameters fully. The description repeats the period value examples but does not add new meaning beyond the schema. It reinforces that the result is a total count, but that is purpose, not parameter semantics.

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 the tool's purpose with a specific verb ('Get'), resource ('total download count for a package'), and scope ('over a period'). It also enumerates acceptable period values, which helps distinguish it from siblings like npm_downloads_bulk (multiple packages) and npm_version_downloads (version-specific counts).

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 description implies usage for single-package download statistics by saying 'for a package', but it does not explicitly state when to use this tool over siblings such as npm_downloads_range or npm_downloads_bulk. No alternatives or exclusions are mentioned, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds operational constraints: 128 package limit, scoped packages unsupported, and the bulk endpoint nature. These are valuable behavioral details beyond annotations, though return format and pagination are not covered.

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 sentences, front-loaded with purpose, then critical constraints. No filler or repetition of schema details.

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 read-only bulk query tool with full schema coverage and safety annotations, the description covers the key use case, constraints (128 max, no scoped packages), and points to an alternative for unsupported packages. It does not describe the exact output shape, but no output schema exists and the task is simple enough that this is minor.

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%: packages and period are already described ('Array of package names to compare (unscoped only)' and 'Period (default: last-week)'). The description adds no new parameter-level meaning beyond reinforcing the unscoped constraint and the bulk limit, which already appears in schema maxItems. Baseline 3 applies when schema covers 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?

Description opens with a specific verb 'Compare' and resource 'download counts for multiple packages over a period', clearly distinguishing it from single-package siblings like npm_downloads. The explicit 128-package limit and scoped-package exclusion further clarify scope.

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?

Explicitly states that scoped packages are not supported and instructs to call npm_downloads separately per scoped package, providing a clear when-not and alternative. However, it does not explicitly contrast with using npm_downloads for single unscoped packages, though the bulk purpose is evident.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns a per-day breakdown, which is useful behavioral context beyond annotations, but it does not disclose rate limits, authentication needs, or edge cases like invalid period formats.

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?

The description is a single, front-loaded sentence that concisely states the core action and outcome. It contains no redundant information or filler, making it highly efficient.

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 simple read-only tool with two well-documented parameters, the description plus schema is largely adequate. It states the return format (per-day breakdown) and scope (over a period), but it does not explicitly differentiate from closely related sibling tools, which is a minor completeness 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?

Schema description coverage is 100%, with both 'name' and 'period' fully described in the schema. The tool description adds no additional parameter semantics; the schema already provides default and allowed formats for 'period'.

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 the tool gets daily download counts for a package over a period, with a per-day breakdown. This specific verb+resource combination distinguishes it from sibling tools like npm_downloads or npm_downloads_bulk by emphasizing daily granularity.

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 description provides no guidance on when to use this tool versus alternatives such as npm_downloads or npm_version_downloads. It does not mention any exclusions, comparisons, or selection criteria, leaving the agent to infer usage solely from the name.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by detailing the data sources evaluated (e.g., security status, deprecation, documentation quality), which goes beyond the annotation's safety profile and helps the agent anticipate the kind of information the tool gathers.

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?

The description is a single, front-loaded sentence that starts with the action verb and succinctly lists the key health dimensions. No redundant filler or repetition exists, achieving excellent conciseness.

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?

The tool is simple (1 parameter, full schema coverage) and annotations cover safety. The description explains what it assesses across multiple dimensions. A minor gap is the lack of any mention of the output format (e.g., score or report), but this is not critical given the tool's straightforward nature and absence of an output schema.

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 single parameter 'name' is fully described in the schema as 'Package name' (100% coverage). The tool description does not add further semantic information about the parameter, so it remains at the baseline 3; the schema carries the entire descriptive burden.

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 uses a specific verb ('Assess') and clearly identifies the resource ('health of a package'). It enumerates concrete dimensions (maintenance activity, download trend, security status, deprecation, documentation quality) that distinguish this holistic health check from sibling tools like npm_audit or npm_downloads, which focus on single aspects.

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 description establishes a clear usage context: the tool provides an overall health assessment. It does not explicitly mention alternatives or exclusion criteria, but the scope is evident from the listed dimensions. This meets the 'clear context, no exclusions' level.

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

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

Annotations already indicate non-readonly and non-idempotent behavior. The description adds meaningful transparency by stating that the secret is never echoed back in responses, which is not present in the annotations or schema.

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 concise sentences with no redundancy. The main action is front-loaded, followed by precise parameter guidance and a key behavioral caveat. Every sentence earns its place.

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?

The description fully explains all three required input parameters, which is the core need. However, there is no output schema or description of what the tool returns on success/failure, leaving the agent unsure about the expected response shape beyond the secret not being echoed.

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%, so parameters are already well documented. The description reinforces target formats and endpoint/secret roles but adds little beyond what the schema provides, aside from the 'never echoed' note which is more behavioral.

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 states a specific verb ('Create') and resource ('registry webhook'), and elaborates the exact target formats. It clearly distinguishes this creation operation from the sibling hook tools (list/get/update/remove) by the action itself.

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 description gives clear context for when to use it—creating a webhook—and precisely defines the target argument formats. It does not explicitly state when not to use it (e.g., for updating an existing hook) or name alternatives, but the creating action is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds a valuable behavioral detail: 'The stored secret is redacted from the response.' This sets expectations beyond the structured metadata.

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, no unnecessary words. The first sentence states the action, and the second provides a key behavioral note. It is appropriately front-loaded.

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 one simple parameter, strong annotations, and a clear description of the action and redaction behavior, the description is complete for this low-complexity tool. The lack of an output schema is mitigated by the note about the returned secret.

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 input schema has 100% coverage for the single parameter 'id', with a clear description 'Hook ID (UUID from npm_hook_list)'. The tool description itself adds no extra parameter semantics, so baseline 3 applies.

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 uses a specific verb 'Get' with a resource 'webhook' and scope 'by its ID'. It clearly distinguishes from sibling tools like npm_hook_list (which lists all webhooks) and mutation tools such as npm_hook_add/update/remove.

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 description implies usage when you have a webhook ID but does not explicitly state when to use this tool over alternatives. No exclusions or alternative tool names are provided; the guidance is only implicit.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable context by stating that 'Secrets are redacted from responses,' which is a non-obvious behavioral detail that helps the agent set expectations. It also clarifies the optional package filter.

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?

The description is extremely concise, with two short sentences that front-load the core purpose, then the optional filter, then the key behavioral note about redaction. No unnecessary words.

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 simple list operation with strong annotations and no output schema, the description covers the essential purpose, filtering capability, and an important output detail (secret redaction). It is complete enough for an agent to select and invoke the tool correctly, though it does not describe pagination behavior explicitly.

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% for all three parameters (limit, offset, package), so the schema is sufficient. The description reinforces the package filter but does not add extra semantics beyond the schema. Baseline 3 is appropriate.

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 the tool's action ('List webhooks') and resource (webhooks), with a specific optional filter by package name. This distinguishes it from sibling hook tools like npm_hook_get, npm_hook_add, npm_hook_update, and npm_hook_remove, which have different actions.

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 description implies usage for listing webhooks and mentions an optional filter, but it does not explicitly contrast with alternatives like npm_hook_get for retrieving a single hook. The usage context is clear, but there are no explicit exclusions or 'when not to use' guidance.

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

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

The description adds no behavioral context beyond the annotations. The destructiveHint: true, idempotentHint: true, and readOnlyHint: false already convey the safety profile, and 'Delete a webhook' merely restates that. There is no mention of permanence, ownership requirements, or error handling, so the description fails to add incremental value.

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?

The description is a single, compact sentence: 'Delete a webhook by ID.' It is front-loaded with the action and resource, contains zero filler, and is appropriately sized for the tool's simplicity.

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 the tool's simplicity (one required parameter, no nested objects, no output schema), the description covers the core action, and annotations supply crucial context about destructive and idempotent behavior. It lacks an explicit statement about return values or permanent effects, but these are not critical for this type of operation, making it nearly complete.

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 already documents the single 'id' parameter with a description 'Hook ID', and the description's phrase 'by ID' aligns with that. With 100% schema description coverage, the description does not need to compensate, and it adds no extra meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 the action ('Delete') and the resource ('a webhook') with a required identifier ('by ID'). It is unambiguously distinct from sibling hook tools like npm_hook_add, npm_hook_get, and npm_hook_update, which perform different operations on the same resource.

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 description implies use when a webhook needs to be removed, but it does not explicitly provide context for when to use this tool versus alternatives like npm_hook_update (modifying) or npm_hook_get (reading). There are no exclusions, prerequisites, or situational guidance, so it earns a mid-range score.

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

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

Annotations already indicate destructiveHint=true, but the description goes beyond by explaining the PUT overwrite semantics: the config is completely replaced, so both fields are always written. It also discloses that the returned hook object redacts the secret, which is useful behavioral context not present in annotations. This adds meaningful transparency without contradicting annotations.

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?

The description is two sentences, but both are information-dense and critical. The first sentence states the core behavior and the overwrite warning, and the second clarifies the secret rotation nuance and the redaction detail. No fluff, every sentence earns its place.

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 3-parameter mutation tool with no output schema, the description covers the essential behavior, the overwrite pitfall, and the return redaction. It doesn't mention error cases or auth requirements, but annotations and sibling context (other hook tools) imply standard conditions. Given the simplicity and complete schema coverage, this is sufficiently complete for correct invocation.

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 schema already documents each parameter meaning. The description adds the crucial nuance that secret is always written and that endpoint is required, but these are also reflected in schema descriptions ('Always written; pass the existing secret...' and 'required — the PUT replaces the whole config'). The description doesn't add significant new parameter semantics beyond what schema provides, so baseline 3 is appropriate.

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 the tool's action: replace a webhook's endpoint AND signing secret. It explicitly distinguishes this from merely changing one or the other, and the warning about the overwrite behavior clarifies the tool's unique destructive scope, setting it apart from sibling tools like npm_hook_add or npm_hook_get.

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 description provides explicit usage guidance: both endpoint and secret are required, and it warns that passing only the endpoint will rotate the secret unintentionally. It tells the user to supply the current secret if they only intend to change the endpoint, which is a clear conditional instruction. While it doesn't name alternatives explicitly, the guidance is sufficient for correct invocation.

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

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

The description discloses significant behavioral details beyond the annotations: it issues 2 requests per direct dependency (10 in flight), has a 60s cap, returns 'NOT_CHECKED' for unreached deps, and flags those as not allowed. It also explains that SPDX expressions are not decomposed and must be added verbatim to 'allowed'. These details are critical for understanding tool performance and output interpretation, and they fully align with the read-only/idempotent annotations.

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?

The description is dense but every sentence earns its place: it leads with the core purpose, then explains the matching semantics, then the network constraints and failure mode. There is no fluff or repetition; the length is justified by the informational density needed for this tool.

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 the tool's complexity (network requests, timeouts, concurrency, special handling of SPDX expressions), the description covers the key operational aspects and even hints at output via the 'NOT_CHECKED' status. However, it does not describe the full return structure (e.g., whether results are a list, map, or report) since there is no output schema. This is a minor gap for an agent needing to interpret the result, but the description provides enough to anticipate common cases.

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 input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining how the 'allowed' parameter behaves (exact verbatim matching, default list, case-insensitive matching), which is not fully evident from the schema alone. It also clarifies the 'version' default implicitly by not contradicting it, though no extra syntax guidance is given for name/version.

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 the tool's action: 'Check the license of a package and its direct production dependencies. Flags missing or non-standard licenses.' It also specifies the scope (direct production dependencies) and the matching behavior, distinguishing it from other npm tools that inspect dependencies or audit security. The details about SPDX expression handling further clarify the exact resource and operation.

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 description implies the tool is for license compliance checking but does not explicitly state when to use it over siblings like npm_audit, npm_dependencies, or npm_dep_tree. No alternatives are mentioned, so an agent must infer the use case from the name and description. There is clear context but no exclusions or routing guidance.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds behavioral scope by specifying 'current maintainers' and 'publish history', clarifying exactly what data is returned. It does not disclose pagination or auth details, but these are minor given the simple read-only nature.

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?

The description is a single, well-structured sentence with no filler. It front-loads the action and resource, making it immediately clear what the tool does.

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 simple one-parameter read tool with strong annotations, the description sufficiently states the outputs (maintainers and publish history). No output schema exists, but the description covers expected content. It is contextually complete within the sibling tool ecosystem.

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 already provides 100% coverage for the single parameter 'name' with description 'Package name'. The description does not add extra parameter-level details, but does reinforce the package context by mentioning 'for a package'. Baseline 3 is appropriate.

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 the verb 'Get' and the resource 'current maintainers and their publish history' for a package. It distinguishes from mutating sibling tools like npm_owner_add/remove by focusing on retrieval. The resource is specific and non-tautological.

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?

Usage context is implied (when you need maintainer info for a package), but the description provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. It does not mention that the package 'name' parameter is required, which is already in the schema.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context about what the tool returns (recipes, tool mappings, CLI fallbacks, message formats) and its purpose to prevent reinventing approaches. This goes beyond the annotations without contradicting them.

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?

The description is three sentences, each earning its place: what it returns, when to call it first, and why it exists. It is front-loaded with the core purpose and avoids any filler.

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 zero-parameter meta-tool with no output schema, the description is complete: it covers the tool's function, usage timing, and content of the guidance. Given the simplicity, nothing important is missing.

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?

There are no parameters, and schema coverage is 100% (the schema is empty). With zero params, a baseline of 4 is appropriate; the description adds no parameter details but none are needed.

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 the tool's purpose: 'Return canonical recipes for common npm operations' — which MCP tool to call, CLI fallbacks, and message format guidance. This distinguishes it from sibling tools by positioning it as the meta-tool that guides selection among them.

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?

Explicitly tells the agent when to use it: 'Call this FIRST when you're not sure how to do an npm operation.' It also clarifies how it supplements alternatives by providing CLI fallbacks when the MCP server can't handle something. This is strong usage guidance.

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

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

The description goes beyond the annotations by disclosing the specific side effect (team memberships are also removed) and the confirm guard requirement. This adds critical behavioral context about what gets destroyed, which is valuable for a destructive operation.

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 tight sentences, front-loaded with the action, followed by the critical side effect and requirement. Every sentence earns its place with no fluff or redundancy.

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 tool with no output schema, the description is complete: it states the action, the side effect, the confirm guard, and the irreversible cascade. It gives enough context to use the tool safely and correctly.

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%, with each parameter already described clearly (org, user, confirm). The description adds rationale for the confirm parameter but does not introduce new semantic meaning for the org and user parameters beyond what the schema provides.

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 uses a specific verb and resource context: 'Remove a user from an org' and clearly distinguishes it from team-level tools by noting 'Their team memberships in that org are also removed.' This differentiates it from siblings like npm_team_member_remove and npm_org_member_set.

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 provides clear context for when to use it (removing a user from an org entirely) and warns about the cascading effect with 'team memberships cascade and cannot be selectively preserved.' It doesn't explicitly name alternatives or when-not-to-use, but the context is sufficient.

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

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

Annotations already cover the safe, read-only, idempotent nature of the tool. The description adds the authentication requirement and that roles are included in the output, but no details on pagination, error cases, or response structure. It provides moderate additional context beyond the annotations.

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?

The description is a single, concise sentence that front-loads the action and resource, and includes essential context (authentication requirement) without redundancy. It is well-structured and efficient.

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 simple read-only tool with one parameter and comprehensive annotations, the description adequately covers purpose and auth. It could include more about response format or exclusions, but given the tool's simplicity and annotation coverage, it is largely complete.

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 input schema has 100% description coverage for the sole parameter 'org', including the note about '@' prefix. The tool description does not add further parameter semantics, so the schema carries the full burden, resulting in a baseline score of 3.

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 a specific action ('List all members') with a specific resource ('npm organization') and includes expected output ('roles owner, admin, developer'). It distinguishes itself from sibling tools like npm_team_members or npm_maintainers by explicitly focusing on org members.

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 description implies usage by stating the purpose and an authentication prerequisite, but it does not explicitly compare to alternatives (e.g., 'Use npm_team_members for team-level membership'). There is no when-to-use or when-not-to-use guidance beyond the clear purpose.

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

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

The description goes far beyond the annotations (destructiveHint, idempotentHint) by disclosing the critical behavior: the registry defaults an omitted role to 'developer', which would silently demote admins/owners. It explains the workaround of reading the roster first and re-sending the existing role. It also notes that omitting role for new users adds them as 'developer'. This is essential behavioral context that annotations do not provide.

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?

The description is somewhat long but every sentence is information-dense. The primary purpose is front-loaded, and the crucial nuance about role omission is explained in a structured flow. No filler or redundant phrasing; the length is justified by the complexity of the behavior.

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 org membership mutation with no output schema, the description covers all necessary aspects: adding vs updating, role omission behavior, the registry's surprising default, and the safety requirement. The confirm parameter is also described in the schema, and the description emphasizes the guard. An agent has enough to invoke this tool correctly.

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%, so baseline is 3. The description adds meaningful semantic detail about the 'role' parameter: the effect of omitting it differs for existing vs new members, and the tool explicitly preserves existing roles. This extra explanation helps the agent pass the correct parameters, exceeding what the schema alone conveys.

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 states a specific verb and resource: 'Add a user to an org or change their role.' It clearly names the action and scope, and differentiates itself from siblings like npm_org_member_remove and npm_owner_add. No ambiguity about what this tool does.

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 description gives clear context for when to use the tool: to add a member or update a role. It explains behavior for both existing and new members, which helps the agent decide based on the scenario. However, it does not explicitly name alternatives or state when-not-to-use, leaving some inference to the agent.

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

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

Annotations already establish this as read-only, idempotent, and non-destructive. The description adds meaningful context by revealing that the result includes access levels and clarifies that 'accessible' covers packages the org owns or has been granted. It does not mention authentication or pagination, but those are not essential given the read-only safety profile.

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?

The description is two concise sentences with the core action front-loaded ('List all packages...'). Every word adds value, and there is no redundant or boilerplate content.

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 single-parameter, read-only listing tool, the description is sufficient: it states the scope ('all packages accessible'), the distinguishing output detail ('access levels'), and the ownership/grant nuance. The rich annotations and simple schema mean no further context is needed for an agent to select and invoke this correctly.

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 input schema fully describes the single required parameter `org` with the note 'Organization name (without @ prefix)' at 100% coverage. The description does not add additional parameter-level details, so the baseline score of 3 is appropriate because the schema carries the semantic burden.

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 uses a specific verb ('List') and identifies the exact resource ('all packages accessible to an npm organization') plus includes the distinguishing detail of access levels. It clearly separates this from sibling tools like npm_user_packages and npm_team_packages by anchoring on the organization scope.

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 description implies usage: use this when you want to see an organization's accessible packages and their access levels. However, it does not explicitly mention when not to use it or point to alternatives such as npm_user_packages for user-scoped listings or npm_team_packages for team-scoped listings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a key behavioral requirement—authentication as an org member—which is not in the annotations. This is useful context that goes beyond the structured data.

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?

The description is two concise sentences. It front-loads the primary action ('List all teams...') and includes only essential extra information (auth requirement). No fluff or repetition.

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 the tool's simplicity (1 parameter, clear purpose) and strong annotations (read-only, non-destructive), the description is mostly complete. It could mention pagination or response format, especially since there is no output schema, but for a straightforward list operation it is adequate.

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 input schema already provides full coverage with a description for the only parameter 'org' ('Organization name (without @ prefix)'). The tool description adds no additional parameter information. With schema coverage at 100%, the baseline of 3 is appropriate.

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 a specific action and resource: 'List all teams within an npm organization.' This distinguishes it from sibling tools like npm_org_members (list members) and npm_team_members (list members of a team), making its purpose unambiguous.

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 description provides clear context for when to use this tool: to list teams in an npm org. It also mentions a prerequisite ('Requires authentication as an org member'), which helps the agent understand preconditions. However, it does not explicitly mention alternative tools or exclusions, so it stops short of full guidance.

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

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

Annotations already indicate non-read-only, non-destructive, idempotent. The description adds valuable behavioral details: grants publish/write permissions and resolves email automatically via /-/user/. This goes beyond the schema and annotations.

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 with no filler. The action, permissions, email resolution, and verification step are all front-loaded and every sentence earns its place.

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 a simple 2-parameter mutating tool with no output schema, the description covers the essential behavior, permissions, and a pre-add verification step. It could mention reversibility or side effects, but the core context is sufficient.

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 has 100% coverage with descriptions for both parameters (name, username). The description doesn't add much beyond noting that email is resolved automatically, which is implicit in 'username'. Baseline 3 is appropriate since the schema already documents 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 states a specific action ('Add a user as a maintainer of a package') with clear resource and scope, distinguishing it from siblings like npm_owner_remove. The mention of publish/write permissions adds specificity.

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?

Provides clear context by recommending npm_collaborators for verification before adding, which implies when to use this tool (after checking current maintainers). It doesn't explicitly state when not to use it, but the verification guidance is actionable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds a valuable behavioral detail: 'Refuses if it would leave the package with zero maintainers (lockout prevention),' which goes beyond the annotation metadata. This provides the agent with a clear safety guardrail.

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?

The description is two sentences, front-loaded with the verb and resource, and includes a useful safety note without any fluff. Every sentence earns its place.

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 simple two-parameter tool with strong annotations, the description covers the core action, the safety behavior, and the scope. It does not describe return values or permissions, but those are not essential given the annotations. The lockout note adds completeness, though explicit when-to-use guidance would make it fully complete.

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 covers 100% of the parameters with descriptions ('Package name' and 'npm username to remove'). The tool description adds no extra parameter semantics, but the schema already provides sufficient meaning. Baseline 3 is appropriate for high schema coverage.

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 the action ('Remove a user from a package's maintainer list') with a specific verb and resource. It distinguishes this tool from siblings like npm_owner_add and npm_maintainers by focusing on removal from the maintainer list.

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 description implies usage for removing a maintainer, but it does not explicitly state when to use this tool vs alternatives (e.g., npm_owner_add for adding, npm_maintainers for viewing). There is no 'when not to use' guidance, leaving the context to be inferred from the tool's name and sibling list.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds useful scope limitations: what fields are returned and that per-version details are excluded. This goes beyond the structured hints, though it stops short of describing potential errors or rate limiting, which are not critical for this simple read operation.

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 compact sentences: the first leads with the verb and resource, the second clarifies the scope exclusion. No filler words, clear punctuation, and front-loaded purpose.

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 single-parameter, read-only tool with no output schema, the description is sufficient. It lists the return fields, clarifies what is not included, and points to the right alternative. No other contextual gaps exist for the agent to invoke it correctly.

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 already provides 100% coverage of the single 'name' parameter, including an example. The tool description adds no further parameter-level semantics. The baseline of 3 applies since the schema does the heavy lifting.

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 'Get package metadata' and enumerates specific fields (description, dist-tags, latest version, maintainers, license, repository, keywords). It also explicitly distinguishes itself from npm_version by noting it does not include per-version details, which pins down its unique purpose among siblings.

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 description provides explicit when-not-to-use guidance ('Does not include per-version details') and names the alternative tool ('use npm_version for that'). This tells the agent exactly when to choose this tool over its sibling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining the interaction between publish_requires_tfa and automation_token_overrides_tfa, which helps interpret the response. It does not mention rate limits or auth, but the annotations reduce the burden.

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 sentences: the first states the purpose with the key fields, the second gives a critical diagnostic interpretation. No redundant words, front-loaded with the verb 'Get'. Every sentence contributes value.

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 simple read-only tool with one parameter and no output schema, the description is complete. It lists the returned settings and explains their significance for a common failure scenario. No gaps in expected behavior or return payload.

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% with a descriptive parameter 'name' including an example. The description does not add anything about the parameter itself, but the baseline of 3 applies given the schema fully handles it.

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 starts with 'Get package access settings' and specifies exactly what settings: visibility, 2FA requirement, and automation token override. This clearly distinguishes it from mutation tools like npm_access_set and npm_access_set_mfa among siblings.

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 description provides a clear context for use: 'Critical for understanding why CI publishing fails' and explains the diagnostic condition. It does not explicitly name alternatives or state when not to use it, but the use case is unambiguous and sufficient for distinguishing from related tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context beyond that: it confirms the tool operates on the authenticated user (implying auth requirements), lists the returned fields, and links the 2FA status to publishing workflow. No contradiction with annotations.

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?

The description is two concise sentences, leads with the action and resource, and every phrase adds value. It is appropriately front-loaded and free of redundancy.

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 a zero-parameter, read-only tool with no output schema, the description is complete. It lists the returned fields, implies the need for authentication, and cites a concrete use case, which is sufficient for an agent to select and invoke it correctly.

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 input schema has zero parameters and schema coverage is 100%, so there are no parameter semantics to document. Per the rubric, zero parameters yields a baseline of 4.

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 uses a specific verb ('Get') and resource ('authenticated user's npm profile') and enumerates the fields returned (name, email, 2FA status, creation date). This distinguishes it from siblings like npm_whoami, which likely returns only the username.

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 explicitly states a key use case: checking whether 2FA is enabled and how that affects token requirements for publishing. This gives clear context for when to use the tool, though it does not explicitly name alternatives or exclusions.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by disclosing that it does NOT perform cryptographic signature verification, certificate-chain verification, or Rekor transparency-log verification. This is valuable behavioral context that prevents misuse.

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?

The description is concise and front-loaded with the main verb and resource, followed by a clear explanation of the output and a necessary limitation note. Every sentence earns its place without redundancy.

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 the tool's simplicity (2 required params, no output schema), the description provides a complete picture of what the tool retrieves and its limitations. It explains the return type conceptually (SLSA provenance and publish attestations) so an agent knows what to expect.

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 input schema already provides 100% coverage with descriptions for both 'name' and 'version', including examples and the requirement for an exact semver. The description adds no additional parameter-level semantics, so the baseline score of 3 applies.

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 uses the specific verb 'Retrieve' with a clear resource ('Sigstore attestations for a specific package version') and explains what will be shown (SLSA provenance and publish attestations). This clearly distinguishes it from sibling tools like npm_signing_keys or npm_trusted_publishers.

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 description explicitly states when NOT to use this tool for cryptographic verification and directs users to a dedicated Sigstore client instead. This provides clear exclusions and an alternative, going beyond a simple 'when to use' statement.

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

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

The description goes beyond the readOnlyHint/idempotentHint annotations by detailing the non-interactive assumptions, the pass/fail/warn checklist return, and the structured actions with exact human-run commands. It also explains why the tool behaves this way (agent constraints), providing rich behavioral context with no contradiction to annotations.

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?

The description is front-loaded with a one-line purpose, followed by a compact, information-dense breakdown of checks and behavioral constraints. Every sentence contributes value—the non-interactive caveat, the checklist scope, and the output mode—without filler.

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 no output schema, the description thoroughly covers return semantics (actionable checklist with pass/fail/warn, exact human commands), prerequisites (non-interactive), and distinguishes itself from related publish operations. It provides everything an agent needs to select and invoke the tool correctly.

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 has 100% coverage for the single parameter 'name' ('Package name to publish (e.g. '@yawlabs/npmjs-mcp')'). The description does not add extra parameter details, so the baseline of 3 is appropriate; the parameter is simple and unambiguous.

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 the tool's purpose: 'Comprehensive pre-publish validation — run before publishing ANY npm package.' It distinguishes itself from sibling tools by covering a broad checklist (auth, 2FA, package name availability, maintainer access, etc.) rather than a single concern like npm_check_auth.

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?

Explicitly instructs to 'run before publishing ANY npm package', and explains the non-interactive context assumptions (no browsers, no OTP entry). It clarifies that 2FA issues are a hand-off to the human, and 'never suggests actions an agent cannot perform', providing clear when-to-use and behavioral boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety behavior. The description adds no extra behavioral context, such as return format, error handling, or pagination, but it does not contradict annotations. This is acceptable but not contributive.

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?

The description is a single, short sentence that conveys the essential purpose without any filler. It is front-loaded and every word earns its place.

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 simple tool with one well-documented parameter, rich annotations, and no output schema, the description is sufficient. It could be improved by specifying the return format or handling of missing READMEs, but these are not essential for basic tool selection.

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 provides 100% coverage with the parameter 'name' described as 'Package name'. The description only repeats this by saying 'of a package', adding no extra semantic value beyond the schema, hence the baseline score of 3.

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 the tool retrieves README content for a package, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like npm_package, which may also provide README in package metadata, so it stops short of full distinction.

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 description provides no guidance on when to use this tool versus alternatives such as npm_package or npm_search. It does not mention exclusions, prerequisites, or context, leaving the agent without direction for tool selection.

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

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

The description adds meaningful context beyond the annotations by identifying the specific source (replicate.npmjs.com) and warning about intermittent availability. It does not detail pagination or return format, but the reliability warning is valuable behavioral information.

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?

The description is two sentences that are front-loaded with the primary action and followed by a necessary caveat. Every word earns its place; there is no redundancy or filler.

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 simple read-only tool with one optional parameter and strong annotations, the description is largely complete. It states the source and warns of availability issues. Omitting response structure is acceptable given the lack of an output schema and the tool's straightforward nature.

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 input schema already fully documents the `limit` parameter (default 25, max 100). The description adds no additional parameter information, so the baseline score of 3 is appropriate given the high schema coverage.

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 the tool's function: retrieving recent package publishes/updates from the npm registry via the CouchDB changes feed. The verb 'Get' and resource 'npm registry' are specific, and it is easily distinguished from sibling tools like npm_search or npm_registry_stats.

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 description implies the tool is for recent changes but does not explicitly specify when to use it over alternatives or when not to use it. The availability note about replicate.npmjs.com is a caveat, not a usage guideline. No direct comparison to sibling tools is provided.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the scope ('npm-wide') but does not disclose additional behavioral traits like response format, aggregation details, or rate limits.

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?

The description is two short sentences with no redundancy. Every word contributes to communicating the tool's purpose and scope.

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 simple one-parameter, read-only tool with strong annotations, the description is sufficient. It specifies the scope and the result (download counts). It lacks explicit comparison to sibling download tools, but this is a minor gap given the tool's simplicity.

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 input schema has 100% coverage for the single 'period' parameter, including its options and default. The tool description adds no further parameter information, so it relies on the schema as the baseline.

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 the tool's action (get) and resource (total npm-wide download counts), and explicitly scopes it as 'npm-wide' and 'overall registry activity'. This distinguishes it from package-specific download tools like npm_downloads, making the purpose unambiguous.

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 description implies usage for registry-wide activity but does not explicitly mention alternatives or exclusion scenarios. Given the many sibling tools for downloads, it would benefit from a direct comparison or a 'use this for X, not Y' statement.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds context about what is analyzed (timeline, gaps, maintenance) but does not disclose additional behavioral traits like pagination, rate limits, or how 'limit' affects analysis. It adds some value but not rich detail.

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?

A single, front-loaded sentence that states the main purpose and key outputs without extraneous words. Every word earns its place.

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 simple read-only tool with 2 well-documented parameters and no output schema, the description sufficiently conveys what the tool does and what it returns (timeline, gaps, maintenance status). It could mention the role of 'limit' more explicitly, but the schema covers it, so the description is adequate.

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 has 100% coverage with clear descriptions for both 'name' and 'limit'. The description does not add any parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.

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 identifies a specific action ('Analyze') and resource ('release cadence of a package'), and elaborates with the outputs ('publish timeline, gaps, and whether the project is actively maintained'). It does not explicitly differentiate from sibling tools, but the focus on cadence is distinct enough to avoid confusion.

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 description implies the tool is for analyzing release timeliness and maintenance status, but provides no explicit 'when to use' vs alternatives, no exclusions, and no comparison with similar npm_* tools. Usage is inferred from the purpose statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is clear. The description adds qualifier examples (e.g., 'not:insecure', 'is:unstable') but does not disclose other behavioral aspects like rate limits, pagination behavior, or result structure. With strong annotations, this is adequate but not enriched.

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?

The description is two sentences, front-loaded with the core action, and every word contributes value. It includes practical examples without unnecessary elaboration, making it highly efficient.

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 no output schema, the description does not explain what the search returns (e.g., list of package names with metadata), nor does it suggest follow-up tools like npm_package for fetching details. The tool has 6 parameters and the description focuses on query behavior but omits integration guidance with the many sibling tools, leaving a moderate completeness 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 already provides 100% coverage of parameters with descriptions. The description adds extra qualifiers ('not:insecure', 'is:unstable') not explicitly listed in the schema's query property, enhancing semantic understanding beyond the structured fields. This justifies moving above the schema-coverage baseline of 3.

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 uses a specific verb and resource: 'Search the npm registry for packages.' This clearly distinguishes it from sibling tools like npm_package or npm_versions. It also provides concrete examples of qualifiers, making the tool's function unambiguous.

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 description clearly states its purpose as searching the registry, and the examples of qualifiers give practical usage context. However, it does not explicitly mention when to use this tool versus alternatives like npm_package for retrieving package details, so it stops short of a full when/when-not guide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully convey the safe, non-mutating behavior. The description adds context that the keys are ECDSA and used for signature verification, but it does not provide additional behavioral details such as return format or authentication requirements. Given strong annotation coverage, this is adequate but not exceptional.

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?

The entire description is a single, focused sentence: 'Get the npm registry's ECDSA signing keys used to verify package signatures.' Every word contributes to the meaning, with no redundancy or extraneous detail.

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 simple, no-parameter, read-only metadata retrieval tool with comprehensive annotations, the description is fully sufficient. The lack of an output schema is not a gap because the purpose is straightforward and the strong annotations cover safety and side-effect expectations.

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 tool has zero parameters, and the schema's 100% coverage trivially satisfies parameter documentation. The description naturally implies a no-input fetch. The baseline for zero parameters is 4, and the description adds no additional parameter-related semantics, which is acceptable.

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 the tool retrieves the npm registry's ECDSA signing keys used for package signature verification. This specific verb+resource phrasing distinguishes it from all sibling tools, which focus on other aspects like packages, auth, or registry statistics.

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 description implies when to use the tool (when signing keys are needed to verify package signatures) and there are no similar sibling tools that would require explicit differentiation. However, no explicit exclusions or alternative tool references are given, so it falls short of a perfect score.

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

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

Annotations indicate this is a non-read-only, non-idempotent, non-destructive operation, but the description adds no extra behavioral context beyond that. It does not mention permissions, side effects, failure modes, or what happens on duplicate teams. The description merely restates the core action without exceeding annotation coverage.

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?

The description is a single concise sentence that communicates the essential purpose and format. It is appropriately short, though it could slightly benefit from a note about the required format being part of the parameter rather than the tool-level description.

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 no output schema, the description does not explain what a successful creation returns, and no mention of error conditions or permissions. Given the tool's simplicity and annotation coverage, it is adequate but has clear gaps for an agent to call it with full confidence.

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 already documents both parameters completely (team with format, description as optional). The description's mention of '@scope:team' is redundant with the schema description. Since schema coverage is 100%, the baseline is 3 with no additional semantic value added.

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 the action ('Create a team inside an organization') with a specific verb and resource. It also includes the exact format '@scope:team', which distinguishes it from related team management tools like npm_team_delete or npm_team_members.

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?

No guidance is provided on when to use this tool versus alternatives, prerequisites, or context such as required authentication or organization membership. The description only states what it does, leaving the agent to infer usage.

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

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

Annotations already indicate destructive and non-read-only behavior, but the description adds valuable detail: it revokes all package permissions, removes team memberships, requires confirm: true, and performs the operation in one call. This goes beyond the structured annotations and gives the agent a clear picture of side effects.

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: the action, the side effects, and the precautionary tip. No redundancy or filler, with the most critical information front-loaded.

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 tool with two parameters and no output schema, the description covers all essential aspects: the operation, required confirmation, consequences, and how to mitigate data loss. It is fully self-contained and leaves no important gaps.

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%, with both team and confirm already well documented. The description echoes the confirm requirement but does not add meaningful parameter-level detail beyond what the schema provides. Baseline 3 is appropriate since the schema carries the parameter semantics.

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 the action ('Delete a team') and specifies the input format ('@scope:team'). It also lists the consequences (revokes all package permissions, removes memberships), which distinguishes it from sibling tools like npm_team_revoke or npm_team_member_remove that operate on narrower scopes.

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 description gives clear usage context: requires confirm: true and warns to preserve grants by listing them with npm_team_packages first. However, it does not explicitly contrast with alternatives like npm_team_revoke, so the guidance is strong but not exhaustive.

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

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

The description adds the authorization requirement, which is useful behavioral context not in annotations. It does not describe side effects (e.g., overwriting existing permissions), but annotations already indicate destructive and idempotent hints, so the bar is lower. The description doesn't contradict annotations.

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 sentences, front-loaded with the core action, followed by format and authorization details. Every sentence earns its place with no waste or redundancy.

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?

The description covers the action, input format, and prerequisites, which is sufficient given the schema richness and annotations. It doesn't describe outputs, but no output schema exists and the info is adequate for selection and invocation.

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 already describes all three parameters with examples and enum values, and the description adds no new parameter-level detail beyond repeating the 'scope:team' format already in the schema. With 100% schema coverage, baseline is 3.

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 the action ('Grant'), the resource ('a team ... permission on a package'), and specific permission levels ('read-only or read-write'). It also gives the format for team scope, distinguishing it from sibling tools like revoke or delete.

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 description provides clear context by stating prerequisites ('Requires org admin or team admin') and implicitly defines when to use it (to grant team permissions). However, it does not explicitly name alternatives or exclusions, so it doesn't fully meet the 'when-not' guidance.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the mutation and idempotency are known. The description adds the team format and org precondition, which is useful context, but does not disclose side effects or permission requirements. No contradiction with annotations.

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 zero wasted words. The core action is front-loaded, followed by the format and precondition.

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 simple 2-parameter tool with full schema coverage and informative annotations, the description covers the essential call context. It could mention permission requirements or error cases, but none are critical for agent invocation.

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%, with both parameters documented ('@scope:team' and 'npm username'). The description repeats the team format and adds the org precondition, but does not add meaning beyond the schema for parameter semantics.

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 uses a specific verb ('Add') and resource ('user to a team'), and clearly defines the team format ('@scope:team'). It is unambiguous and distinguished from siblings like npm_team_member_remove.

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?

Provides clear context including the required team format and the precondition that the user must already be in the org. It does not name alternative tools or explicitly state when not to use it, but the usage context is sufficiently clear.

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

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

Annotations already indicate destructive and non-read-only behavior. The description adds useful context that the user remains in the org, clarifying that only team membership is affected. No contradiction with annotations.

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?

The description is composed of two short, focused sentences. Every word adds value, with no redundancy or filler.

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 simple two-parameter mutation tool with no output schema, the description covers the operation, team format, and the key side effect. It does not mention permissions or error behavior, but these are not critical for such a straightforward tool.

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 input schema provides 100% description coverage for both parameters. The tool description only restates the team format already in the schema, adding no additional semantic value beyond what is available.

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 the tool's function with a specific verb and resource ('Remove a user from a team'). It also specifies the team format ('@scope:team') and clarifies the scope (user remains in the org), which distinguishes it from org-level removal 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 description provides clear context on the team format and the operation's scope, implying when to use it. However, it does not explicitly name alternative tools or state exclusions for 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context (role inclusion, audit use) but does not describe return format or pagination behavior, so it doesn't go beyond annotations in a rich way.

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 sentences with no filler. The first sentence front-loads the core purpose and the second adds high-value complementary/usage guidance, making every word earn its place.

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 simple, non-destructive list tool, annotations cover safety, schema covers all required parameters, and the description indicates the return nature (members with roles). The sibling context is clear, making the description sufficient for selection and invocation.

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 descriptions cover both parameters (org and team) at 100%, so the description doesn't need to repeat param details. The description adds no extra semantic value beyond the schema, so baseline 3 is appropriate.

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 states a specific action ('List') and resource ('all members of a team') and clarifies it includes roles. It also distinguishes itself from the sibling tools npm_team_member_add and npm_team_member_remove by positioning itself as the read/audit counterpart.

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?

Explicitly names complementary tools and gives direct guidance: use this to audit current team membership before adding or removing members. This clearly tells the agent when to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not burdened with safety disclosure. It adds the behavioral detail about returning permission levels, which is helpful, but does not go further into auth requirements, rate limits, or return structure—acceptable given the annotation coverage.

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 sentences with zero waste: the first states the primary action and scope, the second states a valid use case. Information is front-loaded and each clause earns its place.

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 simple read-only list tool with rich annotations and only two parameters, the description is complete. It clearly states what is listed and why it is useful. The absence of an output schema is compensated by the mention of 'permission levels' in the description, making the return content inferable.

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 not add additional meaning to the parameters beyond what the schema already states (org and team names). It simply refers to 'a specific team' which is redundant with the team parameter.

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 uses a specific verb ('List'), clearly identifies the resource ('all packages a specific team has access to'), and adds distinguishing detail about permission levels ('read-only or read-write'). This clearly differentiates it from siblings like npm_org_packages and npm_user_packages by scoping to a team.

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 sentence 'Useful for auditing team permissions' provides a clear use case and context. It does not explicitly exclude alternatives or name sibling tools, but the context is sufficient for an agent to decide when this tool is appropriate.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, and the description adds the valuable context that the team itself is not deleted—only its access to the package is revoked. This clarifies the scope of destructive action beyond what annotations alone convey.

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?

The description is two sentences, front-loaded with the primary action, and each sentence earns its place. It is concise, readable, and free of unnecessary detail.

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 simple tool with two well-documented parameters and no output schema, the description provides sufficient context: what it does, the team format, and an explicit caveat about team deletion. The sibling list provides additional context, and the description is complete for the tool's complexity.

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%: both 'team' and 'package' have descriptions that include the '@scope:team' format and the naming rationale for 'package'. The description does not add meaning beyond the schema, so it meets the baseline for high coverage.

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 the action: 'Revoke a team's access to a package.' It uses a specific verb and resource, and explicitly distinguishes itself from npm_team_delete by noting it does not delete the team itself. This differentiates it from sibling tools like npm_team_grant and npm_team_delete.

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 description explicitly tells the agent when to use this tool (to revoke a team's package access) and when not to (if the goal is to delete the team, use npm_team_delete). This provides clear usage guidance and a named alternative, exceeding the minimum.

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

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

Annotations already indicate destructiveHint: true and readOnlyHint: false, so the description doesn't need to restate those. However, it adds valuable context beyond annotations by explaining the consequence of revoking the currently used token and the reason token creation is not exposed (requires user password). This is useful 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?

The description is compact (four short sentences) and front-loaded with the primary purpose. Every sentence adds meaningful context: operation, prerequisite, risk, and alternative. No filler or redundancy.

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 tool with only two parameters and no output schema, the description covers purpose, confirmation requirement, side effects, and creation alternatives. It could mention the success/error response shape, but that is not critical given the low complexity. The warning about breaking the next call is a strong safety context.

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%, with both tokenKey and confirm having descriptive text. The description reiterates 'Requires confirm: true' and the tokenKey provenance, but does not add meaning beyond the schema. Baseline 3 is appropriate because the schema already carries the semantic weight.

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 opens with 'Revoke an access token by its key (UUID from npm_tokens)', which identifies the specific action (revoke), the resource (access token), and the key mechanism. This clearly differentiates it from sibling tools like npm_tokens (listing) or npm_verify_token (verification).

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 description explicitly states 'Requires confirm: true' as a prerequisite, warns about breaking the next call if revoking the current token, and provides alternative guidance for token creation ('create via https://www.npmjs.com/settings/~/tokens instead'). This gives the agent clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those annotations by revealing that listed tokens may be reusable automation tokens and that publish tokens require OTP in CI, which informs token-reuse decisions. No contradiction with annotations detected.

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 focused sentences: the first states the action, the second lists output fields, and the third gives practical guidance. There is no filler or repetition; the description is front-loaded and every sentence earns its place.

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 simple paginated list tool with rich annotations and parameter schema, the description is complete. It states the user scope, enumerates the returned fields, and adds a real-world use case. No output schema exists, but the description sufficiently covers return content.

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% with clear default and range documentation for both page and perPage. The description adds no parameter-level meaning, but schema already carries the full burden, so the baseline score of 3 is appropriate.

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 opens with a specific verb+resource: 'List all access tokens for the authenticated npm user.' It also enumerates the returned fields (token type, creation date, CIDR restrictions, read-only status), which clearly distinguishes it from sibling write/token-check tools like npm_token_revoke and npm_verify_token.

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 description explicitly frames when this tool is valuable: 'Critical for finding reusable automation/granular tokens that cover your org scope' and warns against 'using publish tokens in CI (which still require OTP).' This gives actionable context for tool selection, though it does not name alternative tools directly or state explicit when-not scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing the authentication requirement ('write access to the package') and the type of data shown (OIDC trust with CI/CD providers). This goes beyond the annotation defaults without contradicting them.

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?

The description is two sentences long, with the main action front-loaded. Every sentence adds meaningful context: the resource and content first, then the authentication requirement. There is no redundancy or fluff.

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 simple one-parameter, read-only tool, the description covers purpose, content, and authentication requirements. It lacks an explicit return-format description, but the absence of an output schema makes that less critical. The description is sufficient for an agent to decide when and how to invoke it.

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 input schema fully describes the single parameter 'name' with an example, so the description does not need to add much. The description adds no extra semantic detail beyond what the schema already provides, earning the baseline score for high schema coverage.

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 the tool's verb and resource: 'List trusted publishing configurations for a package.' It further distinguishes itself by specifying the content (OIDC trust relationships with CI/CD providers) and the purpose (tokenless publishing), which differentiates it from sibling tools like npm_provenance or npm_signing_keys.

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 description implies when to use the tool: to inspect OIDC trust relationships for a package. It also notes the prerequisite of having write access, which is a usage boundary. However, it does not explicitly name alternatives or state when not to use it, leaving some room for interpretation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, providing a strong safety profile. The description adds context about what the tool checks (built-in types vs. DefinitelyTyped) but doesn't disclose return format, error handling, or edge cases. This is comparable to the get_calls example where annotations carry the safety burden and the description adds only moderate behavioral context.

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?

The description is a single sentence that starts with the action verb 'Check' and immediately states the resource and scope. It avoids redundant information and is perfectly sized for the tool's simplicity.

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 simple read-only query tool with comprehensive annotations and full schema coverage, the description adequately covers the purpose. It doesn't explain the return shape, but that is not critical given the tool's straightforward nature and the absence of an output schema. The description is complete enough for an agent to select and invoke the tool correctly.

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 input schema fully documents both parameters (name and version), including the default for version. With 100% schema coverage, the baseline is 3, and the description doesn't add any extra parameter semantics beyond what the schema already provides. No additional explanation of parameters is needed.

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 specifies the tool's purpose: checking TypeScript type support for a package. It distinguishes between built-in types and DefinitelyTyped companion packages, which sets it apart from sibling tools like npm_package that focus on general package info. The action verb 'Check' is specific and the resource is clearly identified.

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 description implies when to use this tool: whenever an agent needs to determine type support for an npm package. It doesn't explicitly mention alternatives or exclusions, but given the tool's name and the explicit focus on TypeScript types, the usage context is clear. A direct comparison with npm_package or npm_health would have improved the score.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description doesn't need to restate mutation risk. It adds value by explaining that clearing the deprecation message is the behavior, and that it is 'more explicit about intent', which helps the agent understand the semantic effect. No contradictions with annotations.

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?

The description is only two sentences, both directly relevant. It starts with the core action 'Clear the deprecation message' and then adds a concise equivalence note, with no wasted words.

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 simple two-parameter mutation tool, the description covers the purpose and relationship to npm_deprecate, and the schema fully defines the parameters. The annotations provide the safety profile, so nothing critical is missing. The only minor gap is lack of mention of permissions or access requirements, but that's beyond what might be expected given the annotations.

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 input schema covers 100% of parameters with descriptions: 'name' as package name and 'versionRange' with the note about omitting to undeprecate all versions. The description's mention of 'package or specific versions' adds no additional detail beyond the schema, so the baseline score of 3 applies.

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 uses the specific verb 'clear' and identifies the resource ('deprecation message from a package or specific versions'), which clearly states the tool's function. It also distinguishes itself from sibling npm_deprecate by explicitly referencing the equivalence, making the purpose unambiguous.

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 description provides guidance by noting equivalence to 'npm_deprecate with an empty message', framing when this tool is the appropriate choice instead of using npm_deprecate directly. It doesn't explicitly list exclusions or alternatives, but the context is clear enough for an agent to select it when the goal is removal rather than setting a deprecation.

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

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

Annotations already indicate destructiveHint=true, but the description adds critical context beyond that: the operation is IRREVERSIBLE, the name is blocked for 72 hours, and cannot be re-published. This goes beyond the structured metadata and gives the agent essential behavioral consequences.

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?

The description is three sentences long, front-loaded with the primary action and scope, followed by the key warning, then the alternative, and finally the confirmation requirement. Every sentence carries essential information with no waste.

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 tool, the description covers the essential context: what it does, its scope, the irreversibility and 72-hour block, the alternative for single versions, and the confirm requirement. There is no output schema, but for an unpublish operation, return values are less critical. The description is complete enough for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.