@yawlabs/npmjs-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.12.2
Disambiguation4/5
Each tool targets a distinct npm resource or operation, with descriptions explicitly clarifying differences between similar tools (e.g., npm_check_auth vs npm_verify_token vs npm_whoami). Some overlap exists between audit variants and download counters, but the descriptions are sufficient to disambiguate.
Naming Consistency4/5
Most tools follow a predictable npm_<resource>_<action> or npm_<action>_<resource> pattern with the npm_ prefix always present. There are minor deviations like npm_package vs npm_search and npm_hook_* vs npm_*_add, but the naming remains readable and mostly consistent.
Tool Count2/5
At 64 tools, the server is well beyond the 25+ threshold for a large toolset. While the domain is broad, the sheer number makes it difficult for an agent to choose correctly without the npm_ops_playbook crutch.
Completeness4/5
The server covers nearly every npm registry operation: metadata, versions, downloads, audits, auth, orgs, teams, collaborators, hooks, deprecation, unpublishing, and access management. Missing direct publish and token creation, but these are intentionally left to the human with explicit tooling.
Average 4.1/5 across 64 of 64 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 59 commits in the last 12 weeks
- Last stable release on August 8, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds only the '@scope:team' format, which is parameter semantics rather than behavioral context. It does not disclose any additional side effects, permission requirements, or typical failure modes, leaving the agent without useful behavioral nuance beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose and the essential format requirement. It wastes no words, but it is extremely brief and leaves out potentially important usage context, so it does not earn a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no output schema, and the description is minimal. It does not explain what happens on success, whether any destructive behavior is involved (despite destructiveHint=true), or what permissions are needed. For a tool with only two parameters, the description could still benefit from a note about prerequisites or side effects, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 repeats the team format already present in the schema ('@scope:team') but does not add any extra meaning about the optional 'description' parameter or how the parameters interact. It neither harms nor significantly enhances the schema's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a team inside an organization' with a specific verb and resource, and it also defines the required team format as '@scope:team'. However, it does not explicitly differentiate itself from sibling tools like npm_team_delete or npm_team_grant, so it earns a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of prerequisites, required permissions, or situations where a different team-related tool would be more appropriate. The context of sibling tools exists but the description does not address it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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 the authentication requirement, which is useful context beyond annotations. However, it does not disclose pagination, error behavior, or rate limits, so it adds only moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no redundant wording. Every sentence serves a purpose: stating what the tool does, what it returns, and its authentication requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter, read-only tool with good annotations, the description adequately covers purpose, output, and auth requirement. It doesn't mention edge cases like nonexistent users or pagination, but these are not critical for basic invocation. Slight deduction for lacking any mention of access-level semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'username' described as 'npm username.' The description does not add further meaning beyond the schema, but the schema already provides sufficient clarity. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource: 'packages published by a specific npm user.' It also states what is shown (package names and access level). However, it does not explicitly distinguish itself from sibling tools like npm_org_packages or npm_team_packages, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It mentions 'Requires authentication' but does not state preconditions, exclusions, or alternative tools. The intended usage is only implied by the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior: it specifies 'production' dependency tree (excluding dev dependencies), 'up to a configurable depth', and that it shows 'full transitive dependency graph with versions', which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the main verb and resource. No redundant phrasing or fluff; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is adequately described for a basic invocation, it lacks details on the output shape (e.g., tree structure format) and edge cases like circular dependencies or unresolvable versions. Given the absence of an output schema, the description could be more explicit. However, annotations cover safety and the schema covers all parameters, so it is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all parameters (name, depth, version) have detailed descriptions. The tool description does not add additional parameter semantics beyond restating the depth and version concepts. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resolve', the resource 'production dependency tree for a package version', and the scope 'full transitive dependency graph with versions'. It is specific enough to distinguish the tool's core function from generic package commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like npm_dependencies, npm_audit_deep, or npm_versions. The description implies it is for full transitive graph resolution, but it does not explicitly state exclusions or mention sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the useful behavioral detail that the returned hook object has the secret redacted, which is not covered by annotations. However, the phrase 'and/or secret' conflicts with the schema's required fields (endpoint and secret are both required), leaving ambiguity about whether partial updates are possible. This inconsistency undermines transparency about how the update actually behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that front-load the action and immediately identify the updateable fields. It includes a valuable note about secret redaction 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate given the complete schema and annotations, but it lacks key context such as prerequisites (e.g., the hook must exist), side effects of updating the secret or endpoint, and clarity on partial versus full replacement. The redaction note is helpful, but the schema-description mismatch leaves a meaningful gap in understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for all three parameters (Hook ID, New signing secret, New HTTPS URL), giving 100% coverage. The description adds little semantic meaning beyond what the schema states, only hinting at 'and/or' which is potentially misleading given the required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a webhook's endpoint and/or secret' clearly identifies the specific action (update) and resource (webhook), and explicitly names the fields that can be changed. This distinguishes it from sibling tools like npm_hook_add, npm_hook_list, and npm_hook_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing webhook, as indicated by 'Update' and the required id field in the schema, but provides no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions. It could have named npm_hook_add for creation or npm_hook_remove for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and non-read-only. The description adds valuable behavioral detail: the secret is never echoed back in responses, which is a security-relevant trait not captured in the schema or annotations. There is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise, front-loaded sentences. It states the action, explains target formats, then defines endpoint and secret behavior without any redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has complete schema and annotations. The description explains target, endpoint, and secret behavior sufficiently for invocation. However, no output schema exists and the description doesn't mention what the response will contain, which would be helpful for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for target, endpoint, and secret. The description repeats these details and adds one new piece (secret is never echoed). Given the schema already handles the heavy lifting, the extra value is minimal, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a registry webhook,' a specific verb+resource that clearly differentiates from sibling tools like npm_hook_list, npm_hook_get, npm_hook_update, and npm_hook_remove. It also enumerates valid target formats, which adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on target types and endpoint requirements, but does not explicitly state when to use this tool versus alternatives such as npm_hook_update for modifying an existing webhook. The usage is implied by the verb 'create,' but no exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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, establishing safety. The description adds concrete behavioral details beyond annotations by specifying exactly what metadata is included (dependencies, dist info, file count, size, deprecation status), helping the agent anticipate the return data. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the verb and resource. Every word contributes value, listing the major metadata categories without unnecessary elaboration. It is appropriately concise for a simple read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters, no output schema, and strong annotations. The description sufficiently conveys what the tool does and what data it returns, which is adequate for an agent to select and invoke it. It lacks details about default version behavior (though that's in the schema) but is otherwise 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'name' and 'version' having descriptions. The tool description does not add meaningful semantic detail beyond the schema; it mentions 'specific version' but does not clarify parameter formats or constraints beyond what the schema already states. Baseline of 3 applies because the schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('detailed metadata for a specific version'), and enumerates specific metadata types (dependencies, dist info, file count, size, deprecation status). This distinguishes it from sibling tools like npm_versions (list versions) and npm_package (general package info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need detailed metadata for a specific version. However, it does not explicitly mention when to use this tool over alternatives like npm_package or npm_versions, nor does it provide any exclusions or alternative tool recommendations. It provides contextual clues but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 context of 'last week' (despite the configurable period) and the interpretive angle of version adoption, but does not disclose return structure or any API quirks. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action, and every word adds value. 'Shows version adoption' provides a useful interpretive note without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool, the description conveys the essential purpose and output concept (per-version counts). Although there is no output schema, the phrasing 'broken down by version' implies the response structure sufficiently. It does not specify the exact format but is complete enough for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'name' and 'period' are described in the input schema. The description only repeats the default period ('last week') without adding extra meaning, so it does not exceed the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('download counts broken down by version'), clearly distinguishing it from sibling tools like npm_downloads (total downloads) or npm_versions (version list). The added insight 'Shows version adoption' further clarifies the tool's unique value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: retrieving per-version download statistics. However, it does not explicitly mention when not to use this tool or name alternative tools for total downloads or custom ranges, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. The description adds beyond that by specifying the team format and the org membership prerequisite, which are behavioral constraints not covered by annotations. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loaded with the verb, and every sentence contributes useful information: the action, the team format, and a prerequisite. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 full schema and annotations, the description covers the essential actions and prerequisites. It lacks explicit alternative tool guidance but otherwise is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with 100% coverage. The description's mention of team format and the user requirement partially reinforces the schema but does not add new syntactic details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a user to a team.' It specifies the team format ('@scope:team') and the user prerequisite, making the tool's purpose unambiguous. It distinguishes itself from sibling tools like npm_team_member_remove by its verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying the team format and that the user must already be in the org, which are important when-to-use conditions. However, it does not explicitly mention alternatives or when-not-to-use this tool relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds that it verifies NPM_TOKEN validity and returns the username. This gives the agent useful behavioral insight into error handling and output beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the primary action and enriched with a use case. Every word 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with strong annotations and a simple return value, the description fully covers what the tool does, why it exists, and when to use it. It mentions the NPM_TOKEN dependency and the username return, which is complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so schema coverage is trivially 100%. With no parameters to document, the baseline is 4, and the description appropriately does not need to add parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the currently authenticated npm user and verifies NPM_TOKEN validity, which is specific and action-oriented. It does not explicitly distinguish from siblings like npm_check_auth or npm_verify_token, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by saying it is 'Essential for debugging auth issues before publishing.' This implies when to use it, though it does not mention alternatives or exclusions. The context is sufficient for an agent to choose this tool appropriately in most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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 clear. The description adds valuable behavioral context: the limit default (50), special value 0 to return all, and the newest-first ordering. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by the key behavioral note about the limit parameter. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only version listing tool with two parameters and no output schema, the description fully covers behavior (ordering, limit semantics) and is complete. No missing information needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters. The description reiterates the limit behavior (default 50, 0 = all) but does not add new meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists published versions of a package with publish dates, ordered newest first. This distinguishes it from sibling tools like npm_version (likely a specific version detail) and npm_dist_tags (tags, not versions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: list versions of a package. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous and distinct from sibling tools, so 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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, destructive, and idempotent hints. The description adds valuable context beyond annotations: the update-if-exists behavior, the role enum semantics, and the 'omit role to keep existing role' rule. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the main action and role options, then explain the update behavior. Every sentence adds relevant information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the core operation, role semantics, and idempotent behavior. The confirm parameter is critical but only in schema; however, the schema's description is sufficient. Given no output schema and straightforward params, the description is reasonably complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline is 3. The description adds 'Omit role to keep existing role' which clarifies optionality beyond schema. It also lists allowed roles, reinforcing the enum, but the main added value is the omit-role behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Add' and 'change' targeting a clear resource ('user to an org'), and explicitly lists the valid roles. It distinguishes itself from sibling tools like npm_org_member_remove by stating the idempotent update behavior, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (adding or updating org membership) and provides behavioral context (role enumeration, update-if-exists). It does not explicitly name alternatives or exclusions, but the scope is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds useful behavioral context: the tool grants publish and write permissions and resolves the user's email via /-/user/, saving the agent from supplying it. It does not contradict annotations, and it discloses the key side effect of granting permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding distinct value: the action, the permission effect, and the email resolution plus verification hint. It is front-loaded with the primary purpose and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter mutation tool, the description is quite complete. It covers the action, effects, parameter handling, and a verification step. No output schema exists, so return value details are not required. It could mention idempotency or side effects further, but annotations cover destructive and idempotent hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with clear descriptions. The tool description adds extra meaning by explaining that the username is sufficient and no email needs to be supplied because it is resolved internally. This goes beyond the schema's per-parameter descriptions and helps the agent understand the data flow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add a user as a maintainer of a package.' It also specifies the resulting permissions ('publish and write permissions'), which uniquely identifies this tool versus siblings like npm_owner_remove or npm_collaborators. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit alternative: 'Use npm_collaborators to verify before adding.' This tells the agent when to check first. However, it does not explicitly state when NOT to use this tool (e.g., for removing owners), though that is implied by the context and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior, but the description adds significant context: it shows a warning on install, uses HTTP API with NPM_TOKEN to avoid 2FA issues, enforces a 1024-character message limit, and gives a common 422 troubleshooting path. This goes well beyond the structured metadata and provides actionable behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each earning its place: purpose, behavioral effect, auth rationale, and troubleshooting. It is front-loaded with the core action and avoids any redundant or verbose wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool, the description covers the essential context: what it does, how it authenticates, constraints (character limit), and common failure troubleshooting. Combined with rich annotations and full schema coverage, it provides a complete operational picture without needing an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the property descriptions already explain the meaning of name, message, and versionRange including semver nuances. The tool description does not add parameter-level semantic information beyond the schema, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Deprecate a package or specific versions.' This unambiguously distinguishes it from siblings like npm_undeprecate and npm_unpublish_version. The additional context about warning messages and API usage further clarifies the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (to deprecate) and highlights a key advantage over CLI auth: bypassing 2FA friction. It also provides troubleshooting guidance pointing to npm_versions on 422 errors. However, it does not explicitly name alternatives like npm_undeprecate or state when not to use this tool, missing a bit of explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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 meaningful context beyond these: it surfaces username, 2FA status, and whether writes are likely to succeed, and notes it's faster than running writes. This provides behavioral insight not present in 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose, and every sentence contributes value. No redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is complete: it explains what it does, when to use it, what it surfaces, and why it's beneficial. The tool's simplicity makes this 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so the baseline is 4. The description correctly focuses on the tool's behavior rather than parameter details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool verifies the NPM_TOKEN and surfaces its capabilities (username, 2FA status, write likelihood). This specific verb+resource combination distinguishes it from sibling tools like npm_whoami or npm_check_auth, which focus on identity or auth status in different ways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this FIRST when debugging any write failure to rule out auth issues before trying other fixes,' giving clear when-to-use guidance. It also compares against running writes and interpreting errors, though it doesn't name specific alternative tools explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description significantly enhances the read-only annotations by detailing case-insensitive SPDX matching, flagging behavior for missing/non-standard licenses, and the subtle limitation that SPDX expressions are not decomposed and must be added verbatim to `allowed`. This is valuable beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, then behavioral specifics and a key limitation. Each 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, matching logic, and edge cases, making it largely complete for a check-style tool with good annotations. The lack of an output schema means return format isn't described, but this is a minor gap given the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 100%, the baseline is 3. The description adds semantic depth by explaining how `allowed` works: case-insensitive matching and the need for verbatim SPDX expressions. This goes beyond the schema's simple parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the license of a package and its direct production dependencies, and flags missing or non-standard licenses. This specific verb+resource combination distinguishes it from siblings like npm_dependencies or npm_audit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 this tool (license compliance checking) but does not explicitly mention alternatives or when-not-to-use. The scope (direct production dependencies) and matching rules imply its use, but there is no direct comparison to related npm_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both parameters. The description adds minimal semantic value beyond emphasizing 'Requires confirm: true', which is already encoded in the schema as const. It does not compensate with additional details, hence the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool unpublishes an ENTIRE package (all versions), which is a specific verb+resource+scope. It distinguishes itself from the sibling tool npm_unpublish_version by explicitly mentioning 'all versions' and directing single-version unpublishes elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides usage guidance: 'For single-version unpublish prefer npm_unpublish_version.' This names the alternative and clarifies when to use this tool vs. another. The warning about irreversibility and the 72-hour block also informs decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds critical detail: irreversibility, 72-hour block, and exact dist-tag behavior (auto-reassign only 'latest', others left unset). This goes well beyond the annotation's binary flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence carries unique weight—irreversibility, time window, safety mechanism, CLI flow, sibling distinction, and dist-tag side effects. No filler; well-structured with the core action first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive irreversible operation, this description is comprehensive: it explains consequences, constraints, side effects, and next steps. Absence of output schema is acceptable as no structured output is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all three parameters with descriptions, so baseline is 3. The description reinforces the confirm parameter's purpose but doesn't add new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it unpublishes a specific version of a package. Differentiates from sibling npm_unpublish_package by explicitly naming it as the alternative for full-package unpublish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: only works within 72 hours, requires confirm=true, and for full-package unpublish use npm_unpublish_package. Also advises on reassigning dist-tags with npm_dist_tag_set after side effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![npmjs-mcp MCP server](https://glama.ai/mcp/servers/YawLabs/npmjs-mcp/badges/card.svg)](https://glama.ai/mcp/servers/YawLabs/npmjs-mcp)

Score Badge

Copy to your README.md:

[![npmjs-mcp MCP server](https://glama.ai/mcp/servers/YawLabs/npmjs-mcp/badges/score.svg)](https://glama.ai/mcp/servers/YawLabs/npmjs-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/YawLabs/npmjs-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server