DepScope

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

Beyond annotations (read-only, idempotent), the description adds performance (<100ms for 100 items) and the exact status categories returned, providing rich behavioral context.

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

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

Three compact sentences with clear USE WHEN and NOT sections; 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?

Despite no output schema, the description details the return format with concrete status values, covers performance, usage guidance, and parameter structure, making it fully complete for a batch check tool.

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

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

Schema coverage is 0%, but the description restates 'batch of (ecosystem, package) pairs', which adds little beyond the schema. It does not clarify the structure or allowed values beyond the schema definition.

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 defines the tool as a fast pre-flight filter for batch checking ecosystem-package pairs, and distinguishes it from dep-tree audit by naming the sibling tool scan_project.

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 (before npm/pip install) and when not to use (not a dep-tree audit), with a specific alternative tool referenced.

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 return value structure ({compatible, conflicts[], notes}) and does not contradict annotations (readOnlyHint, idempotentHint). Annotations cover safety; description adds output format.

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 terse sentences: question, usage, return. No redundant words. Front-loaded with 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 query tool with one parameter and full schema coverage, the description is complete. Annotations provide safety profile. No output schema, but description explicitly states return structure.

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 already provides description for the sole parameter (Package -> version map) with 100% coverage. Description adds context with example values (next@15), enhancing meaning 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 the tool's purpose: checking if a multi-package version combo works together. It distinguishes from siblings like check_package (single package) by specifying multi-package and 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?

Explicit 'USE WHEN' with concrete examples (pinning stacks, before version matrix). This guides the agent on appropriate usage and implicitly excludes single-package checks.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds the return shape ({is_malicious, threat_tier, source}) and the external source (OpenSSF/OSV), which provides useful behavioral 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?

The description is extremely concise: three sentences covering purpose, usage guidelines, and return value. Every sentence adds value, and it 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?

Given the tool's simplicity (2 simple params, no output schema), the description provides purpose, usage, and return details. It lacks examples or explanation of threat_tier/source, but the overall context is sufficient for a check tool. The annotations cover safety, so completeness is adequate.

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

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

Schema coverage is 0%, so the description must compensate for parameter meaning. However, the description does not mention the 'package' or 'ecosystem' parameters explicitly, relying on their names and the ecosystem enum. This leaves the agent without added semantic detail beyond what the schema already 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's purpose: 'Supply-chain malware check against OpenSSF/OSV'. It uses a specific resource (malware check) and distinguishes from siblings by explicitly saying '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?

The description provides explicit when-to-use conditions: 'USE WHEN: about to suggest install of an unvetted/unfamiliar package; name came from a blog/tutorial.' It also advises ordering relative to sibling tools: 'Call BEFORE check_package for untrusted pkgs.'

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?

Discloses return format (~2k tokens, specific fields) beyond annotations which already indicate read-only and idempotent behavior. 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.

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

Two sentences with clear headings (USE WHEN, RETURNS) that are front-loaded and efficient, 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?

Despite no output schema, description explicitly lists all return fields and token size, making it complete for an agent to understand expected output.

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?

Parameters are well-documented in the schema itself (100% coverage). Description adds no extra semantic value for parameters beyond listing return fields.

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 it returns a machine-readable JSON report and distinguishes from sibling get_package_prompt by specifying use case for programmatic parsing.

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 says 'USE WHEN: you need to programmatically parse specific fields' and directs to an alternative otherwise, with sibling name 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 declare readOnlyHint=true and destructiveHint=false. The description adds the return structure {is_typosquat, likely_target, confidence} and confirms read-only behavior. 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.

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

Description is extremely concise: one sentence for purpose, one for usage, one for returns. Front-loaded and efficient, 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's simplicity (2 required params, no output schema), the description covers the main output and usage. However, missing parameter documentation prevents a perfect score.

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% meaning no description for parameters. The tool's description does not explain 'ecosystem' or 'package' beyond their existence, despite the schema having an enum for ecosystem. This is a critical gap.

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's a 'Typosquat detector' and provides specific examples (e.g., 'lodsh', 'reqeusts'). It distinguishes from sibling tools like check_malicious by focusing on name similarity.

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 lists three scenarios: when name differs from a well-known package by 1-2 chars, copy-paste from unreliable source, downloads near zero but name looks familiar. This provides clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds return format (table-shaped JSON, one row per package) and confirms idempotent behavior 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?

Two sentences, front-loaded with core purpose, then usage guidance, then return format. No wasted words; efficient and structured.

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 key aspects: constraints (2-10 packages, same ecosystem), return shape (table-shaped JSON), and comparison dimensions. Lacks error handling or missing package behavior, but sufficient for most use cases.

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

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

Schema description coverage is 50% (packages has description, ecosystem doesn't). Description does not elaborate on individual parameters but adds context on comparison dimensions (health, vulns, etc.), providing partial compensation.

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 verb (comparison), resource (packages), and scope (health, vulns, downloads, maintainers, last release). Distinguishes from single-package check_package and find_alternatives sibling tools.

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

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

Provides explicit usage guidance with 'USE WHEN: X vs Y / should I pick X or Y'. Lacks explicit when-not-to-use, but context signals imply 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 indicate a non-read-only, non-destructive, non-idempotent tool. The description adds a return value ({ticket_id} or {anomaly_id}) but does not disclose other behavioral traits like side effects, rate limits, or auth requirements. 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 extremely concise—two lines plus a list of categories. It front-loads the purpose and provides immediate actionable guidance. Every word earns its place.

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

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

For a complex tool with 13 parameters and no output schema, the description covers the main use cases and ties parameters to categories. It could note error handling or fallback behavior, but the current content is adequate 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.

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by grouping parameters per kind and explaining the return format, but does not provide additional syntax or constraints beyond the schema. The context of usage enhances understanding.

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

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

The description clearly states it is an inbound ticket tool for specific categories (bug, listing, security, anomaly, partnership). Each category has a distinct purpose, and the tool is differentiated from sibling tools that are all about checking or scanning packages.

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 for each kind, guiding the agent on the appropriate scenario for each. For anomaly, it specifies the required fields (tool_called, observed, expected), effectively telling the agent when to use this versus other tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and no destructive actions. The description adds that it returns a curated list with reasons and stdlib flag. 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.

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

Concise: only three sentences. Structured with USE WHEN and RETURNS sections. Every sentence adds value. 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?

For a simple lookup tool, the description covers purpose, usage, and return format. However, it lacks details on how alternatives are curated or any limitations (e.g., coverage). Still, sufficient for typical use.

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 description must compensate. It implicitly clarifies 'package' via usage context but does not explicitly explain 'ecosystem'. The enum helps, but the description could add more detail.

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 provides curated replacements for deprecated/unhealthy packages, including stdlib built-ins. It distinguishes from sibling tools like check_package or get_health_score by focusing on 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?

Explicit 'USE WHEN' conditions are given: package flagged AVOID/URGENT, querying for alternatives, before guessing. This provides clear guidance and reduces misuse.

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 read-only, idempotent, non-destructive behavior. Description adds return format (array of objects with area, description, hint) and constrains scope to same package major jumps, which is 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 concise sentences: purpose, usage, return format and distinction. No fluff, front-loaded with key information. Every sentence adds value.

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

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

Fairly complete: includes purpose, usage, return shape, and sibling differentiation. Lacks explanation of optional version parameters and potential edge cases (e.g., non-major bumps), but given annotations and lack of output schema, it provides adequate context.

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

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

Schema has 4 parameters with 0% coverage; description hints at version parameters ('between two majors') but does not explicitly map to from_version and to_version or clarify optionality. It adds some value but insufficiently compensates for low schema documentation.

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

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

Clearly states tool provides breaking changes between two majors of the same package, with a concrete example (next@14→15). Distinguishes from sibling get_migration_path by specifying same package vs different packages, making purpose unambiguous.

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

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

Explicitly states when to use: when user is bumping a major, before recommending a major upgrade. Also explains when not to use it by distinguishing from get_migration_path, which handles different packages.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, setting a high baseline. The description adds value by stating the return format ({score, verdict}) and positioning it as the 'cheapest go/no-go gate', but does not elaborate on other behavioral traits like rate limits or data freshness. Still, it adds 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?

The description is concise (3 sentences) with effective front-loading of the core purpose. Every sentence adds value: purpose, usage condition, alternative guidance, and return format. No redundant or unnecessary words.

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

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

Given the tool's simplicity, the description covers the key aspects: purpose, use cases, limitations, and return format. It is complete enough for an agent to understand and invoke correctly. Minor gap: no mention of the verdict values or scoring criteria beyond the threshold, but the return type is stated, making it functionally 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?

The input schema has 2 parameters (package, ecosystem) with 0% coverage in the description. The description does not explain or elaborate on these parameters; it only implies them through context. Given low schema coverage, the description should compensate but does not, forcing the agent to infer from names alone, which is adequate but not helpful beyond the schema.

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

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

The description clearly states the specific verb 'get' and resource 'health score', defines its output range (0-100) and meaning (>=70 safe), and distinguishes it from siblings like check_malicious, check_typosquat, and get_package_prompt, making its purpose unambiguous.

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

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

The description explicitly states when to use ('CI gating or pkg already screened'), when not to use ('NOT a first screen'), and provides specific alternative tools to run first ('check_malicious + check_typosquat') and for verbal verdict ('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 and idempotentHint. The description adds return format but no additional behavioral traits beyond what annotations provide. 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.

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

The description is concise with three clear segments: what it does, when to use, and return structure. Front-loaded with 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?

No output schema exists, but return structure is described. Parameter details are missing. For a tool with 3 parameters and no schema descriptions, more context about inputs would improve 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 0%, so description must compensate. However, it only mentions 'specific package version' without detailing the three parameters (package, ecosystem, version). No syntax, constraints, or defaults are explained.

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 returns non-CVE known bugs for a specific package version, distinguishing from sibling tools like get_vulnerabilities. The verb 'get' and resource 'known bugs' are specific.

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 specifies when to use: 'USE WHEN: unexpected behavior that is NOT a security issue; a pinned version misbehaves.' This provides clear context and implicitly advises against using for security issues.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds 'cheapest call' and exact return shape, enhancing transparency without contradicting.

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

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

Two sentences: first states purpose and cost, second gives usage guidance and return shape. No wasted words, 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?

Complete for a simple lookup tool. Describes return shape and usage context. Lacks mention of error behavior or if package not found, but not critical given simplicity.

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

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

Schema has 0% description coverage, but description does not elaborate on parameters beyond the schema (ecosystem enum is shown in schema). For a simple tool, this is acceptable but doesn't compensate 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?

Clearly states it returns the latest published version and deprecation flag. Distinguishes from sibling check_package by specifying it's the cheapest call and when to use.

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

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

Explicitly tells when to use ('only a version string matters') and when not to (if also need health/vulns, use check_package). Provides clear alternative.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds that it returns a structured object with specific fields, confirming no side effects. No contradictions 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?

Two sentences, front-loaded with purpose and use case, then 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?

The description explains the return value fully given no output schema. It covers the essential aspects of a moderately complex tool. Sibling tools like 'get_breaking_changes' exist but this tool's scope is distinct and well-defined.

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 67% (2 of 3 parameters have descriptions). The description mentions 'both endpoints known' but adds little semantic value beyond the schema. Baseline 3 is appropriate as the description does not compensate for the missing parameter description on ecosystem.

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 provides a 'prescriptive migration plan between DIFFERENT packages' with specific outputs like rationale, diff, breaking changes, and effort minutes. It distinguishes itself from siblings by focusing on cross-package migration rather than single-package checks.

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 provides a 'USE WHEN' condition: replacing specific packages (e.g., request→axios). This gives clear guidance on when to use. However, it does not mention when not to use or explicitly reference alternative sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: plain-text output (~300 tokens), 75% cheaper than JSON, and content details (verdict, health, etc.). 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 concise (two sentences plus usage directives) and well-structured with USE WHEN, PREFER THIS, and RETURNS sections. 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 the tool's simplicity (2 parameters, no output schema), the description adequately covers output format, content, and cost benefit. However, it could be slightly more complete by explicitly noting that the output is a plain-text brief and listing the verdict options.

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%, meaning the description does not explain the parameters (package, ecosystem) beyond what the schema provides. The schema has an enum for ecosystem but description adds no semantics, making it insufficient for a tool with two required parameters.

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

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

The description clearly states the tool's purpose: providing an LLM-optimised package brief including verdict, health, vulnerabilities, alternatives, and maintainer alerts. It distinguishes itself from sibling tools like check_package by recommending preference 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?

The description explicitly tells when to use the tool (e.g., to reason over a package and drop output directly in context) and specifies preference over check_package. This provides clear guidance for the agent.

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

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

Description adds return structure and non-bias claim beyond annotations (readOnly, idempotent). Does not contradict annotations; adds value.

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

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

Two sentences plus use-case and return format. Front-loaded, no fluff. Every sentence earns its place.

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

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

Given no output schema, description specifies return format explicitly. Lacks explanation of rank_delta or weekly_growth_pct, but overall adequate for the tool's simplicity.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add extra meaning to parameters beyond what schema already 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?

Description clearly states 'get trending packages' with specific metrics (rank-delta, weekly growth %) and provides a use case. It distinguishes from siblings (e.g., check_*, compare_*, etc.) effectively.

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 provides clear context for when to invoke, and mentions non-bias by training data. Could mention when not to use or alternatives, but context is clear enough.

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 valuable behavioral details: 'Runs 4 backend endpoints in parallel' and that each return field 'may be null if its backend call failed', which goes 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.

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage guidelines, parallelism behavior, return structure. 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?

The description covers return structure with possible nulls and parallelism, which is sufficient for a 2-param tool without output schema. However, it does not mention rate limits or authentication requirements, though annotations cover safety.

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 0% schema description coverage, the description must explain parameters but only mentions 'package' implicitly via context. It does not describe what 'package' or 'ecosystem' mean beyond the schema, leaving the agent to infer from the enum list and tool purpose.

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 'One-call aggregate of ALL non-CVE supply-chain trust signals', listing specific trust categories (maintainer, scorecard, quality, provenance) and distinguishing it from CVE-focused tools like get_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?

The 'USE WHEN' section explicitly lists concrete scenarios (hardened/regulated env, SBOM/compliance, small-pkg ownership review, choosing between candidates), providing clear guidance on when to use this tool over alternatives.

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

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

Annotations already indicate read-only and idempotent behavior; description adds return structure details and confirms non-destructive nature. 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.

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

Two-line description with return format is concise and front-loaded with purpose, 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?

Provides return structure but lacks details on version parameter alignment, pagination, or error handling. Adequate for a simple tool but has gaps.

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

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

Schema coverage is 0% and description does not explain the parameters beyond the schema. It mentions 'specified version' but no version parameter exists in the schema, causing potential confusion.

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

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

The description clearly states the tool retrieves CVE/OSV advisories for a package, distinguishing it from siblings like get_known_bugs or get_trust_signals by focusing on security 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 cases: security-sensitive projects and user queries about CVEs, but lacks explicit guidance on when not to use it or direct 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 indicate readOnly, idempotent, and openWorld hints. The description adds the return format ('{primary, variants[]}') and mentions 'correct flags,' but does not elaborate on behavioral nuances like network access or error handling. With annotations covering core traits, a score of 3 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?

Three short sentences that front-load the purpose and usage. Every sentence contributes essential information without redundancy or extraneous detail.

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

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

For a straightforward query tool with 3 parameters and no output schema, the description covers purpose, usage context, and return format. It lacks detail on the 'variants' field and how flags are selected, but overall it's sufficient for an agent to decide 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 33% (only 'ecosystem' has an enum; 'package' has no description, 'version' has bare description). The tool description does not elaborate on parameter meanings beyond what the schema provides. Given low coverage, the description fails to compensate, resulting in limited added value for parameter understanding.

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 the canonical install command for any package manager, specifying the action ('emitting an install line') and the resource ('install command(s) per ecosystem'). It distinguishes from sibling tools like check_package or get_latest_version, none of which return install commands.

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 WHEN: emitting an install line and you want correct flags,' providing clear context. However, it does not indicate when not to use the tool or list alternative tools, though no direct siblings exist for install commands.

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. Description adds that it returns {exists}, clarifying output shape. 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.

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

Three brief sentences, no fluff. Purpose, usage, and return are front-loaded efficiently.

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 two required parameters, the description covers the essentials. No output schema needed. Could mention success/error cases, but low complexity reduces need.

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%, meaning description provides no details on parameters beyond their existence. Does not explain ecosystem enum or package format. Agent lacks context on acceptable values.

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?

States clearly it's a boolean existence check for registry packages. Distinguishes from sibling tools like check_bulk or check_compatibility by focusing solely on existence.

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 describes when to use: before install commands or when verifying training data names. Could be improved by noting when not to use (e.g., for detailed checks), but clear positive 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, openWorldHint, idempotentHint. Description adds return format (recommended_version, walk_log[]) and confirms behavior aligns with 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?

Two-sentence description, front-loaded with core purpose, then usage and return. 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?

For a read-only, idempotent tool with 5 parameters and no output schema, the description conveys essential behavior and return shape. Could improve by covering parameter defaults or edge cases, but sufficient for basic use.

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 only 40%; description provides no additional parameter details beyond the schema. Does not explain 'ecosystem' values, 'package' format, or 'include_prerelease' behavior, leaving gaps for the agent.

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

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

Description clearly states it finds the highest safe version under a CVE severity threshold with semver constraints, and gives specific use cases (package.json, dependabot). This distinguishes it from siblings like get_latest_version or get_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?

Explicit 'USE WHEN' clause tells the agent when to invoke (resolving package lines or dependabot), implying not for bulk or malicious checks, which belong to siblings like check_bulk or check_malicious.

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, destructiveHint, so safety profile is clear. Description adds behavioral context about two invocation modes, return structure (exact-match vs search results), and that context parameter is optional for error mode. 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 3-sentence structure: summary sentence, USE WHEN block, RETURNS block. Front-loaded with key distinction (error vs query). 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?

With no output schema, description adequately documents the two return formats. Input schema is fully described. The usage is clear given sibling tools. Minor omission: no explicit guidance if both error and query provided (assumed mutually exclusive). Overall, highly informative for an error resolution tool.

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

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

Schema coverage is 100% with descriptions already defining parameters. Description reinforces error vs query triggers and adds return value details, which schema lacks. Context parameter is mentioned but not elaborated, so some value added 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?

Clearly states the tool maps errors or free-text queries to verified fixes, with two distinct modes (error and query). Differentiates from sibling tools like check_package or get_known_bugs by focusing on resolution rather than package metadata.

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 section explicitly states when to use: when user pastes concrete error/stack or describes symptom. Advises 'Always prefer this over guessing a fix', providing clear guidance on selection between error and query parameters.

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 read-only, idempotent, and non-destructive behavior. The description adds significant nuance: two input shapes with different limits and return formats, and the nature of the output (JSON or text brief). 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 dense but well-structured with clear sections (what it does, input shapes, when to use, returns). It front-loads the purpose. Could be slightly more organized with bullet points, but 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?

Despite having no output schema, the description explains the return format (JSON or text) based on input shape. It covers all key aspects: input constraints, use cases, output differentiation, and comparison with sibling. Very complete for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the two alternative input shapes, constraints on array lengths, and conditions for using ecosystem parameter. This goes beyond the schema descriptions.

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

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

Clearly states the tool performs a full audit of dependencies with per-package health and vulnerability information, and outputs prioritized actions. It explicitly distinguishes itself from sibling check_bulk by noting that scan_project fetches full health and 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' conditions: when user pastes package.json/requirements.txt or asks 'is my stack OK'. Also directly contrasts with check_bulk, guiding the agent to choose the right tool.

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