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

Discloses behavioral details beyond annotations: uses abbreviated packument format, bounded fetch limiter, renders ASCII tree with deduplication. Explains side effects of depth on include flags. No contradiction with annotations (readOnly, idempotent, etc.).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with Args, Returns, Examples sections. Every sentence adds value. Front-loaded with main purpose. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description explains return format thoroughly (counts summary, direct lists, tree). Covers all aspects given complexity. Provides examples. Complete for agent understanding.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant meaning: explains each parameter's purpose, default values, and interactions. For example, include_dev is ignored when depth>1. Examples show usage. Goes well beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get dependency information for a specific version of an npm package' with specific verb and resource. It distinguishes from siblings like npm_package_info and npm_package_versions by focusing on dependencies and transitive trees.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context on when to use depth and explains that include flags are ignored when depth>1. Includes examples like 'express', depth=2. Could explicitly mention alternatives for version listing but is sufficient.

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

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

Annotations already confirm safe, idempotent, read-only behavior. The description adds value by detailing the comprehensive return structure (license, repository, keywords, etc.), providing transparency about the output beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (about 10 lines) with clear sections for Args, Returns, and Examples. It is front-loaded with the purpose, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter and no output schema, the description fully explains the return fields (version, license, maintainers, etc.) and provides examples. No gaps remain for correct invocation.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with a clear description for package_name. The tool description reinforces this with examples (e.g., 'react', '@anthropic-ai/sdk') and shows how to invoke, adding semantic clarity beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get comprehensive information about an npm package' clearly states the action and resource. It lists specific data fields (latest version, description, license, etc.) and distinguishes from siblings like npm_package_dependencies and npm_package_readme.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by listing the information returned, but does not explicitly state when to use this tool versus alternatives like npm_package_dependencies or npm_search. No when-not or alternative guidance is provided.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond annotations, notably that large READMEs are truncated to 25000 characters with a notice. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear first sentence stating the purpose, followed by details on content, parameters, return value, and examples. It is concise and front-loaded, though slightly verbose with the formal 'Args:' and 'Returns:' sections.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description fully explains the return value format (markdown, truncation notice) and provides examples. The tool is simple with one parameter, and the description covers all necessary information 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the baseline is 3. The description restates the parameter's purpose and provides examples like 'zod' and 'express,' which add slight contextual value but do not significantly enhance the meaning beyond the schema's 'npm package name' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the README content of an npm package.' It uses a specific verb and resource, and the tool is well-distinguished from siblings like npm_package_dependencies, npm_package_info, etc., which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus its siblings. It only explains what the tool does, leaving the agent to infer usage context. No explicit when-to-use or when-not-to-use advice is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety profile is clear. The description adds detail about the returned metrics but does not reveal additional behavioral traits such as rate limits, authorization needs, or data freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured. It starts with a clear summary sentence, then details the metrics, arguments, return structure, and examples. Every section provides necessary information without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description thoroughly explains the return value with a breakdown of scores and metrics. It also includes examples. For a simple one-parameter tool, this provides complete context for an agent to understand inputs and outputs.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents the single parameter. The description reinforces its purpose (the npm package name) and ties it to the tool's functionality, but does not add new constraints or format details beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets quality, popularity, and maintenance scores for an npm package from npms.io. It lists specific metric categories and provides examples, distinguishing it from siblings like npm_package_info which would focus on general details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool provides (scores, metrics) but does not explicitly state when to use it over alternatives like npm_package_info or npm_search. The examples imply it's for comprehensive scoring, but no direct comparison or exclusion criteria are given.

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

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

Annotations already mark it as readOnly, idempotent, and non-destructive. The description adds significant behavioral detail: priority order of type sources, DefinitelyTyped fallback, typesVersions handling, and return format specifics. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and example cases. It is somewhat lengthy but each sentence adds value. Front-loads the main action effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains the return markdown fields. Covers all aspects: bundled types, DefinitelyTyped check, typesVersions, and install command. Sufficient for the tool's complexity.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description repeats the parameter names and defaults but adds no new semantic detail. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The title and description clearly state the tool checks for TypeScript type definitions in npm packages. It specifies three bundled-type sources, DefinitelyTyped check, and typesVersions. This distinguishes it from siblings like npm_package_info or npm_package_dependencies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use (to check TypeScript support). It includes examples showing expected results for different packages. However, it does not explicitly state when not to use or mention sibling tool alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return structure (version list with publish dates, dist-tags, deprecation notices) and providing examples. It does not contradict annotations and offers additional behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence summary, followed by parameter details, return information, and examples. Every sentence adds information; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters and no output schema, the description adequately covers the return structure and examples. It does not explicitly address edge cases like missing packages, but the main functionality is well-explained.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters. The description adds examples and clarifies constraints (e.g., limit range 1-100, default 20) beyond the schema. The examples demonstrate parameter usage, adding practical semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool's action: 'List published versions of an npm package with release dates, sorted by most recent first.' This is a clear verb (List) + resource (npm package versions), and it distinguishes from sibling tools like npm_package_dependencies and npm_package_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use (listing versions) but does not explicitly state when not to use this tool or mention alternative tools. The intended use is implied by the purpose, but no exclusions or comparisons are given.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds context: returns list with 'name, version, description, keywords, quality scores' and links. Does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Efficient use of sentences: main purpose, return fields, args, returns, and examples. Front-loaded with core action. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given high schema coverage and no output schema, description fully covers search behavior, parameters, and return structure. Examples add practical completeness.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3). Description adds meaningful examples of query strings and elaborates on limit constraint (1-30, default 10). Provides value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Search the npm registry for packages matching a query.' Distinguishes from sibling tools that focus on specific package details (e.g., npm_package_info), dependencies, etc. Examples further clarify scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Examples illustrate usage, but no explicit guidance on when not to use this tool vs alternatives (siblings not mentioned). Agent lacks information on when to prefer search_package vs package_info or dependencies.

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