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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds useful context beyond annotations: it is DB-only, <100ms for 100 items, and returns a specific status enum. This enriches the behavioral model without contradiction.

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

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

The description is compact and well-structured with USE WHEN, NOT, and RETURNS sections. Every clause adds value; it is not padded with filler or repetition.

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

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

Given the tool's simplicity, the description covers the essential context: what it does, when to use it, what it returns, and performance characteristics. It also disambiguates from a closer sibling, making it complete for an agent to decide and invoke.

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

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

The schema has 0% description coverage, but the description compensates by explaining 'items' as (ecosystem, package) pairs and referencing a 100-item batch. It adds semantic meaning to the single parameter without repeating the schema's structural details.

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 gives a specific verb+resource: 'Fast pre-flight filter for a batch of (ecosystem, package) pairs.' It clearly states what it does and what it catches (hallucinated names, stdlib, typos, known-bad), and distinguishes itself from scan_project by explicitly saying it is not a dep-tree audit.

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

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

It provides an explicit 'USE WHEN' scenario (about to emit npm/pip install) and a 'NOT' exclusion with an alternative tool (scan_project for dep-tree audit). This gives clear guidance on when to use this tool versus siblings.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds the return structure ({compatible, conflicts[], notes}), which helps the agent understand what to expect. No contradictions with annotations.

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

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

The description is very concise, using a question format for purpose, a clear USE WHEN section with examples, and a RETURNS specification. Every sentence provides useful information 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?

The description gives a clear purpose, usage scenarios, and return shape, which is sufficient for a simple tool with good annotations and a clear schema. It could be slightly more detailed about the contents of 'conflicts[]', but overall it's complete enough for an agent to select and invoke 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 already describes the 'packages' parameter with an example (100% coverage). The description provides an additional example in the use-case context, but doesn't add significant semantic meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool's function: checking if a specific multi-package version combo is verified to work together, with a concrete example (next@15 + react@19 + node@22). It also distinguishes from sibling tools like check_package and check_bulk by focusing on multi-package version compatibility.

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

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

It provides explicit USE WHEN scenarios: pinning a stack and before recommending a version matrix. However, it doesn't explicitly mention alternatives or when not to use the tool, so it falls short of a perfect score.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds the return shape '{is_malicious, threat_tier, source}' and the ordering recommendation relative to check_package, providing useful context 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?

Three sentences with clear markers (USE WHEN, RETURNS) and no filler. Every sentence contributes meaningful guidance.

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

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

For a simple read-only lookup with two parameters and no output schema, the description covers purpose, usage context, and return contract. It omits edge cases like unknown packages or rate limits, but these are minor given the tool's simplicity and annotation coverage.

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

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

Schema coverage is 0% and the description gives no parameter details. The schema provides an enum for ecosystem but 'package' is a bare string; the description does not clarify package name formatting, version inclusion, or other nuances.

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

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

The description opens with 'Supply-chain malware check against OpenSSF/OSV', clearly stating the tool's function and data source. It also distinguishes from sibling check_package via the directive 'Call BEFORE check_package for untrusted pkgs'.

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

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

Explicitly provides 'USE WHEN: about to suggest install of an unvetted/unfamiliar package; name came from a blog/tutorial' and 'Call BEFORE check_package for untrusted pkgs'. This gives clear conditions and an alternative tool.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond that: response size (~2k tokens), machine-readable format, and a concrete return shape. It doesn't contradict annotations and enriches the behavioral profile.

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

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

The description is highly efficient: three short sentences encapsulate what the tool does, when to use it, and what it returns. It is front-loaded with the most important information and contains zero filler.

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

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

For a read-only reporting tool with strong annotations, the description covers the essential context: return type, token size, and key fields. It omits some details (e.g., scoring scale), but the absence of an output schema is mitigated by the explicit return structure. Adequate for the tool's complexity.

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

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

Schema description coverage is 67%, which is moderate. The description does not add new meaning for the parameters beyond what the schema already defines (e.g., package name, version, ecosystem). However, the return structure implicitly clarifies the semantics of the package parameter. This is adequate but not outstanding.

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

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

The description uses a specific verb and resource ('Full machine-readable JSON report') and clearly distinguishes from get_package_prompt by contrasting the two use cases. It also lists the return fields, making the tool's scope unmistakable.

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?

Explicit 'USE WHEN' clause identifies the intended scenario (programmatic parsing for CI gating, UI, sub-field extraction) and provides a direct alternative ('Otherwise prefer get_package_prompt'). This is a model of clear usage guidance.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive). The description adds valuable behavioral details about the detection criteria and the return format {is_typosquat, likely_target, confidence}, going beyond what annotations provide. No contradiction exists.

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

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

The description is very concise and well-structured with clear labels 'USE WHEN' and 'RETURNS'. It front-loads the primary purpose and efficiently conveys use cases and output 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?

The tool is simple with only 2 params and no output schema. The description covers purpose, usage, and return format explicitly. However, it lacks parameter descriptions, which is a minor gap given the schema's 0% coverage. Still, the description is mostly complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explicitly define the 'ecosystem' or 'package' parameters; the examples (lodsh, reqeusts) imply the package name but leave ecosystem unexplained. The description adds minimal semantic value beyond the bare schema.

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

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

The description starts with 'Typosquat detector', which clearly states the tool's function. It also provides specific use-case scenarios (name differs by 1-2 chars, copy-paste from unreliable source) that help distinguish it from sibling tools like check_malicious or check_package.

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

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

The description explicitly lists 'USE WHEN' conditions, giving clear guidance on when to use this tool. However, it does not mention when not to use it or name alternative tools, so it lacks exclusions but still provides strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the return format (table-shaped JSON) and the dimensions compared, but does not detail potential behaviors like rate limits or data source freshness. This is adequate given the safety annotations.

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

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

The description is two sentences, front-loaded with purpose, and every part adds value: the comparison attributes, the package range, and the use trigger and return type. No waste.

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

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

For a tool with two parameters and no output schema, the description covers the main aspects: what it compares, when to use it, and the general return format. It lacks details on exact JSON fields or error cases, but the listed attributes give sufficient context for typical usage.

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 50% (only 'packages' has a description). The description adds the semantic constraint 'same ecosystem', clarifying the relationship between parameters, but does not explain the ecosystem enum or the output structure beyond mention of table-shaped JSON. This partially compensates but not fully.

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

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

The description clearly states it performs a side-by-side comparison of 2-10 packages, listing specific attributes (health, vulns, downloads, maintainers, last release) and the 'same ecosystem' constraint. This distinguishes it from sibling tools like check_package (single package) or find_alternatives.

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 explicit when-to-use guidance ('USE WHEN: X vs Y / should I pick X or Y'). Does not mention when not to use or alternatives, but the use case is clearly scoped.

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

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

The description supplements annotations by explaining that anomaly routes to structured triage and stating the return value ({ticket_id} or {anomaly_id}). It doesn't contradict annotations, and the annotations already convey that this is a mutating operation (readOnlyHint=false).

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

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

The description is concise and front-loaded with a clear purpose, but the all-caps and dense single-paragraph structure makes it slightly harder to scan. Still, every sentence contributes useful information.

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

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

With 13 parameters, no output schema, and no required fields, the description provides enough context for an agent to know when to use it and what to expect in return. The category routing and anomaly requirements are covered, though it doesn't mention potential side effects or response format details beyond IDs.

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 detailed parameter descriptions, so the baseline is 3. The description adds value by mapping category-specific usage to the kind parameter and emphasizing anomaly fields, slightly enhancing the schema's guidance.

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

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

The description clearly identifies the tool as an inbound ticket creator for five specific categories (bug/listing/security/anomaly/partnership), with a specific verb 'reporting' and resource. It distinguishes itself from sibling analysis tools by its contact/ticket nature.

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 explicit 'USE WHEN' guidance for each category, including special requirements for anomaly (tool_called+observed+expected). This makes it clear when to use this tool instead of siblings, though it doesn't explicitly list 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 readOnly, idempotent, and non-destructive hints. The description adds 'curated' (not live, likely authoritative) and shows the output structure, contributing to transparency without contradicting annotations.

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

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

The description is three concise, purposeful sentences: definition, use cases, output format. It is front-loaded and every sentence adds value, with no redundancy.

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

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

The description covers purpose, usage, and return shape, which is sufficient for a simple lookup tool. However, parameter semantics and potential edge cases (e.g., no alternatives found) are not addressed, leaving slight gaps.

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

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

Schema description coverage is 0%, and the description does not explain the parameters. The term 'package' is implied by the purpose, but 'ecosystem' is never mentioned. The schema enum helps, but the description provides no added meaning.

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

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

The description clearly states a specific verb and resource: 'Curated replacements for deprecated/unhealthy packages'. It also includes an example and distinguishes itself from sibling tools by focusing on alternatives rather than checks or scans.

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

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

The description provides explicit 'USE WHEN' conditions (pkg flagged AVOID/URGENT, asking for replacements, before guessing), but it does not mention when not to use it or name alternative sibling tools. This is clear context without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds useful context by specifying the scope (same package) and the exact return shape, 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.

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

The description is compact and front-loaded, covering purpose, usage, differentiation, and return schema in four sentences. Every sentence contributes 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?

The description provides usage context and return structure, but lacks details about optional parameters and their defaults. Since there is no output schema and the input schema has no descriptions, the tool is not fully self-contained for an agent; however, the core use case is well covered.

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 0%, so the description must explain parameters. However, it only provides an example (`next@14`→`15`) and does not clarify the semantics of optional from_version/to_version, default behavior, or version format. This is a significant gap given the schema has no descriptions.

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

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

The description clearly states the tool's function: retrieving breaking changes between two majors of the same package, with a concrete example (`next@14`→`15`). It also distinguishes it from get_migration_path, making the resource and scope explicit.

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

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

"USE WHEN: user is bumping a major; before recommending a major upgrade" explicitly defines the appropriate context. The note "Different from get_migration_path (same pkg vs. different pkg)" provides an alternative and clarifies when not to use this tool.

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 false. The description adds the score threshold and return format {score, verdict}, enriching the behavioral profile without contradicting annotations.

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

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

The description is compact and well-structured with USE WHEN/NOT/RETURNS labels. Every sentence serves a clear purpose with no redundancy.

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

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

For a simple read-only score tool with two parameters and no output schema, the description covers purpose, usage context, return format, and threshold. This is 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 0%, and the description does not elaborate on the parameters package and ecosystem. While the names are self-explanatory and the ecosystem enum is provided, the description adds no additional semantics 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 specifies a single 0-100 health score with a concrete threshold (>=70 safe), and distinguishes itself from siblings by calling itself the cheapest go/no-go gate. This clearly identifies the action and resource.

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

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

Explicitly states when to use (CI gating or when already screened) and when not to use (not a first screen), and names alternatives check_malicious + check_typosquat and get_package_prompt. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the non-CVE scope and return format, but it does not disclose additional behavioral traits like rate limits, result ordering, or potential version ambiguity. With annotations carrying much of the burden, a mid-range score is appropriate.

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 effectively structured with labels 'USE WHEN' and 'RETURNS'. Every sentence adds value: purpose, usage conditions, and return format. No fluff or redundancy.

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

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

The description provides the return format (bugs[] with title, fixed_in, workaround) compensating for the lack of output schema. It covers purpose, usage, and output adequately for a simple read-only tool. Minor gaps remain in parameter semantics, but overall completeness is strong.

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 0%, and the description only mentions 'a specific package version', which loosely maps to package and version but does not explain the required ecosystem field or provide meaningful semantics. With 3 parameters and no schema descriptions, the description should compensate far more for parameter clarity.

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 'Non-CVE known bugs for a specific package version', which names the resource (bugs) and scope (specific package version). The 'Non-CVE' distinction differentiates it from the sibling get_vulnerabilities tool, providing a clear purpose and 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?

Explicit 'USE WHEN' conditions are given: unexpected behavior that is NOT a security issue, or a pinned version misbehaves. The 'NOT a security issue' clause implicitly excludes get_vulnerabilities, but no alternative tool is named explicitly. This is clear context, though alternative naming would score higher.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context beyond these: 'cheapest call' signals low cost, and the RETURNS line discloses the exact output shape ({latest, deprecated, published_at}). No contradictions with annotations.

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

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

Three concise sentences front-load the core functionality and include a use case, alternative, and return format. No wasted words; every sentence earns its place.

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

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

For a simple two-parameter, read-only tool with no output schema, this description is complete: it states the result format, when to use it, and what not to use it for. The annotations cover safety traits, and the low complexity means no further behavioral details are needed.

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 0%, but the description provides no parameter-level guidance. It does not explain what ecosystem or package mean, nor give examples or format expectations, leaving the schema's raw types and enum as the only source. This fails to compensate for the lack of schema descriptions.

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

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

The description explicitly states the tool returns the latest published version and deprecation flag, with a clear scope ('only a version string matters'). It distinguishes itself from the sibling check_package by noting it is the 'cheapest call' and specifying when to use which.

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 explicit when-to-use guidance ('USE WHEN: only a version string matters') and names an alternative tool for additional needs ('If you also need health/vulns use check_package'). This is a model example of usage differentiation.

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 readOnly=true and idempotent=true, so safety is covered. The description adds the output shape (RETURNS: {rationale, diff, breaking_changes[], estimated_minutes}) and clarifies it produces a literal code diff, giving useful behavioral context beyond the annotations.

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

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

The description is compact: one sentence with clear STRUCTURE (purpose, USE WHEN, RETURNS). Every word adds value, and the format is easy to scan. No 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?

With no output schema, the description correctly carries the return format. It also covers usage context, prerequisite, and param spirit via examples. For a 3-parameter tool with strong annotations, this description is fully sufficient.

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

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

Schema descriptions cover 67% of parameters (to_package and from_package are described). The description's examples (e.g., request→axios) illustrate the from/to relationship and ecosystem, but it does not add detailed parameter semantics beyond what the schema already provides. It adds some value through concrete migration examples.

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

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

The description clearly states a specific deliverable: 'Prescriptive migration plan between DIFFERENT packages' with explicit output components (rationale, diff, breaking changes, effort). It distinguishes itself from siblings like get_breaking_changes by offering a full migration plan rather than only breaking changes.

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 'USE WHEN' clause gives concrete scenarios (request→axios, moment→dayjs, flask→fastapi) and a prerequisite ('both endpoints known'). It does not explicitly name alternatives or exclusion criteria, but the use cases make the tool's niche clear.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: plain-text output, ~300 tokens, ~75% cheaper than JSON, and the specific content components (verdict, health, vulns, alternatives, maintainer alerts). This is valuable behavioral disclosure.

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

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

The description is concise (~75 words) and well-structured: main value proposition first, then usage conditions, preference over alternatives, and return format. Every sentence adds value with no redundancy.

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

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

Given the simple two-parameter schema, strong annotations, and no output schema, the description sufficiently explains purpose, output content, and usage context. It covers what the tool returns, why it's useful for LLMs, and when to use it, making it complete for an agent.

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 0% and the description does not explicitly explain the two parameters (package and ecosystem). While the parameter names and enum for ecosystem are self-explanatory, the description fails to compensate for the lack of schema descriptions. It adds no meaning beyond the field names.

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 returns an LLM-optimised package brief with a verdict (SAFE/AVOID/URGENT/MALICIOUS) plus health, vulns, alternatives, and maintainer alerts. It explicitly differentiates from sibling check_package by noting it's plain-text, cheaper, and preferred in 95% of LLM cases.

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 explicit 'USE WHEN' guidance (reasoning over a package, dropping output directly in context, 'is X safe') and explicitly recommends preferring this over check_package in most LLM scenarios. This gives clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description does not need to cover those. It adds valuable behavioral context by stating the data is 'live' and that recommendations are not biased by training-data cutoff, plus it describes the return shape. This goes beyond the annotations without contradicting them.

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

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

The description is compact and well-structured with a clear lead sentence, a USE WHEN clause, and a RETURNS specification. Every sentence carries information—there is no fluff or repetition—making it easy for an agent to quickly parse.

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

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

For a tool with three optional parameters and no output schema, the description provides sufficient context: it explains the use case, the return format, and the live-data characteristic. It could optionally mention pagination or default limits, but those are in the schema, so the description is nearly complete.

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

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

All three parameters have descriptions in the schema, so schema coverage is 100%. The tool description does not add extra meaning to the parameters themselves; it only mentions output fields like rank and growth. Since the schema already handles parameter semantics, a baseline of 3 is appropriate.

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

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

The description immediately states it returns 'Live trending packages with rank-delta and weekly growth %', which is specific and distinguishes it from sibling tools that focus on vulnerabilities, compatibility, or malware. The USE WHEN clause provides a concrete query ('what is rising in npm/PyPI/Cargo right now') and adds a unique value proposition (not biased by training-data cutoff), making the purpose unmistakably clear.

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 USE WHEN clause gives explicit context for when to invoke this tool, which is more than most tool descriptions provide. However, it does not explicitly state when not to use it or mention alternatives among the sibling tools, so it falls short of a perfect 5.

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?

Beyond the annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral context: it runs 4 backend endpoints in parallel and each returned field may be null if a backend call fails. This discloses performance characteristics and partial failure behavior, which is helpful for agents.

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

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

The description is four sentences, each with a distinct purpose: scope, use cases, execution model, and return structure. There is no redundancy or filler, and the most important information is front-loaded.

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

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

For a composite read-only tool with no output schema, the description fully covers what it does, when to use it, how it executes (parallel), and what it returns (keys and null behavior). It provides enough context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It only indirectly references 'package' through 'deep-vetting a package' and does not explain the 'package' or 'ecosystem' parameters, their formats, or how they are used. The ecosystem enum is self-documenting, but package semantics are underspecified.

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

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

The description clearly states it aggregates all non-CVE supply-chain trust signals (maintainer trust, OpenSSF Scorecard, quality, provenance), using a specific verb ('aggregate') and resource. It distinguishes itself from sibling tools like get_vulnerabilities and get_health_score by focusing on non-CVE signals.

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

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

The description provides explicit USE WHEN guidance: deep-vetting a package beyond CVEs, hardened/regulated environments, SBOM/compliance, small-pkg ownership review, and choosing between healthy candidates. It implies exclusion of CVE-only use cases but does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld. The description adds the return structure ({vulnerability_count, vulnerabilities[] with id, severity, cvss, fixed_in}) and clarifies version scoping. This provides useful context beyond annotations, though the 'specified version' mechanism is ambiguous.

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

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

The description is compact and well-structured, with a leading purpose clause followed by clear USE WHEN and RETURNS sections. Every sentence adds value, and the formatting aids quick parsing by an agent.

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

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

With no output schema, the description provides a return format, which is good. However, the ambiguity around specifying a version (since no version parameter exists in the schema) is a notable gap. For a simple two-parameter tool, the description is mostly complete but falls short on this critical detail.

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 0%, so the description must explain parameter semantics, but it only implicitly references the version via 'or specified' without detailing how to specify it (e.g., package@version). It does not clarify the package string format or the ecosystem enum values beyond what the schema already provides, leaving significant ambiguity.

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 that the tool returns CVE/OSV advisories for a package, either for the latest or a specified version. This specific verb+resource+scope distinguishes it from sibling tools like get_known_bugs or check_malicious, which address different concerns.

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 explicit 'USE WHEN' conditions, including security-sensitive projects and user queries about CVEs, plus a prerequisite ('you already know the pkg exists'). However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, so it lacks full exclusions.

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

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

Annotations already cover read-only, idempotent, and open-world behavior. The description goes beyond these by detailing the return shape ({primary, variants[]}) and the broad scope ('every package manager'), adding useful context about what the agent can expect.

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 in three logical chunks: purpose, usage condition, and return format. Every sentence earns its place with no redundant phrasing.

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

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

For a simple tool with three parameters and clear annotations, the combination of purpose, usage condition, return format, and read-only/idempotent annotations provides a solid understanding. It could mention error behavior or how version defaults work, but overall it is sufficiently complete for agent invocation.

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

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

Schema description coverage is low (33%); only 'version' has a description. The description lists example package managers, making 'ecosystem' semantics clear via the enum, and 'package' is self-evident as a package name. However, it does not clarify edge cases like scope syntax or version format, so the description adds minimal value beyond the schema.

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

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

The description clearly identifies the resource being operated on (install commands) and the specific action (returning canonical versions) across all major package managers. This distinguishes it from sibling tools that check, compare, or scan packages rather than generating install snippets.

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 explicit 'USE WHEN' clause tells the agent exactly when to invoke this tool (emitting install lines with correct flags). It does not explicitly mention when not to use it or name alternatives, but sibling names make the distinction clear.

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

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

Beyond the annotations (readOnly, idempotent), the description reveals the return format ({exists}) and positions the tool as a registry check, implying remote lookup. It doesn't discuss rate limits or failure modes, but the annotations already cover the safety profile, so the added context is useful.

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

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

The description is extremely concise: one main clause plus 'USE WHEN' and 'RETURNS' sections. No wasted words; each segment adds value and the structure is front-loaded with the core purpose.

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

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

For a simple boolean check with read-only annotations, the description covers purpose, usage, and return shape. However, it omits parameter explanations and error/edge-case behavior, leaving minor gaps for a simple tool. The absence of an output schema is mitigated by the explicit return format.

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 description makes no mention of the 'package' or 'ecosystem' parameters. With schema_description_coverage at 0%, the description provides zero parameter semantics, forcing the agent to rely solely on the schema's type/enum definitions. There's no compensation for the low coverage.

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

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

The description opens with 'Boolean registry existence check,' a specific verb-noun phrase that clearly identifies the tool's function. It distinguishes from sibling tools like check_malicious or check_typosquat by focusing solely on existence, and the 'RETURNS: {exists}' adds further clarity.

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

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

The description provides explicit 'USE WHEN' conditions, including checking before emitting an install command and verifying training-data-generated names. It lacks when-not scenarios or alternative tool references, so it's clear but not fully differentiated from siblings.

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?

Description discloses the selection logic (highest version below severity tier) and return format (recommended_version, walk_log), adding value beyond the read-only/idempotent annotations. The walk_log implementation detail is a distinctive behavioral disclosure. However, it doesn't specify edge cases like no safe version found.

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

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

Three concise sentences, front-loaded with the core action, followed by usage cues and return shape. No extraneous content.

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

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

The tool has 5 parameters and no output schema, but the description provides the return shape and core algorithm. It lacks details on include_prerelease behavior and error conditions, but is sufficient for typical use. Given the annotations and sibling context, it's fairly complete.

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

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

Schema covers only 40% of parameters, so the description must compensate. It adds semantics for constraint (semver) and severity tier (matching min_severity), but leaves package, ecosystem, and include_prerelease to the schema. Partial compensation only, so a 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?

Clearly states the tool's function: selecting the highest version below a CVE severity threshold while honoring semver constraints. This distinguishes it from siblings like get_latest_version (no severity filter) and get_vulnerabilities (just lists vulnerabilities).

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 explicit USE WHEN guidance for package manifest updates and dependabot resolution. Does not name alternatives or state when not to use, but the context is clear.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by specifying return formats for both modes (exact-match vs. search results) and mentioning 'verified fix' and confidence. This goes beyond the annotation baseline, though it doesn't cover limitations like rate limits or auth, which are likely not needed given the read-only nature.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. The USE WHEN and RETURNS sections are clearly delineated, and every sentence provides actionable information. There is no redundant fluff or repetition of schema details.

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

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

For a tool with four parameters, a nested object, and no output schema, the description is quite complete. It explains when to use each parameter, provides concrete examples, and describes return types. However, it does not clarify what happens if both `error` and `query` are supplied, or how `context` affects results beyond the schema description, leaving a small gap in 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 description coverage is 100%, providing baseline meaning for each parameter. The description adds semantic value by explaining the relationship between `error` and `query` as mutually exclusive modes, clarifying that `limit` applies only in query mode, and giving example values. This exceeds the schema alone, though not by a huge margin.

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

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

The description clearly states the tool's function: mapping an error or free-text query to a verified fix. It distinguishes itself from siblings by focusing on error resolution, which none of the listed sibling tools directly address. The verb-resource pair is specific and immediately understandable.

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 includes explicit 'USE WHEN' conditions for both error and query inputs, telling the agent exactly which parameter to pass in each case. It also advises preferring this tool over guessing, but does not explicitly state when-not to use it or name alternative tools for exclusion, so it falls just 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.

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

Annotations already declare readOnly, destructive, idempotent hints. Description adds input format variants, return types, and action labels—valuable beyond annotations. 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.

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

Concise at ~4 sentences, with bold-like emphasis. No wasted words, but could be better structured (e.g., bullet points). Still efficient.

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

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

Covers input/output, limits, and use cases. No output schema exists, but description explains return types. Missing error handling details, but adequate for the tool's purpose.

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 clarifies dual input shapes, max counts, and return formats. Adds significant meaning beyond the schema's field descriptions.

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

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

Clearly states 'full dep-list audit' with specific actions (REMOVE NOW, etc.) and distinguishes from sibling check_bulk by noting it fetches full health/vulns. Verb+resource+scope is explicit.

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

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

Explicitly states use cases (pasting package.json, checking safety) and differentiates from check_bulk. Lacks explicit exclusions for single-package checks, but the context is clear.

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