depsonar

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it scans workflow files, knows 30+ popular actions, and names examples. 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 core purpose is front-loaded in the first sentence, followed by a coverage note and two example queries. The examples are useful but slightly redundant, making the description just above average in conciseness.

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

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

The description explains what the tool scans and its known-action coverage, but it does not describe the output or return value. Since no output schema is present, this is a notable gap. With only two optional parameters and safe read-only semantics, it is otherwise adequately complete.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds no parameter-level detail, but the schema already adequately documents 'project' and 'directory'.

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 'Scan' with resource 'GitHub Actions workflow files' and the goal 'outdated or deprecated actions'. It clearly distinguishes itself from sibling tools by targeting GitHub Actions workflow files specifically.

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 example user queries ('Check my GitHub Actions versions', 'Any deprecated actions in my workflows?') that make the intended usage clear. However, it does not explicitly mention alternatives or when not to use this tool, leaving a minor gap.

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 label this as read-only, idempotent, and non-destructive. The description adds behavioral context about reading a cache file and providing instant responses, as well as a fallback suggestion to run a scan. However, it does not detail the exact output format or how stale cache entries are handled.

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

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

The description is three sentences: purpose, mechanism, fallback. The example queries add practical value without bloating the text. 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 zero-parameter tool with no output schema, the description covers the core function, the caching behavior, the instant response, and the fallback when cache is absent. It is fully adequate 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 has zero parameters, so schema coverage is 100%. The description appropriately focuses on behavior rather than parameter semantics, which are not applicable. Baseline 4 for zero-parameter tools.

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 'Show pending dependency alerts from the last background scan', specifying the verb 'show', the resource 'dependency alerts', and the source 'last background scan'. This distinguishes it from live scan tools like depsonar_scan and depsonar_live_cve.

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

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

It explicitly mentions that it reads the cache written by the background checker (no live scan, instant response) and suggests running depsonar_scan or setting up the background checker if no cache exists. This provides clear guidance on when to use it and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by naming the actual audit mechanisms (npm audit, cargo audit, pip-audit, composer audit, govulncheck), which implies external tool invocation and potential network access. It also highlights a cautionary timing rule. 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 and well-structured. It front-loads the primary purpose, includes a critical usage note, and provides three clear example queries. Every sentence contributes to understanding the tool's function and usage. The use of a bold 'CRITICAL' callout adds emphasis without padding.

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 (two optional parameters) and thorough annotations, the description covers the essential aspects: purpose, trigger timing, and example usage. It does not describe the return format in detail (no output schema), but the examples imply a list of CVEs/vulnerabilities, which is reasonable for a scan tool. It could mention potential runtime or network dependencies, but those are not critical given the read-only annotations.

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

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

The input schema already provides a description for both parameters (project and directory) with 100% coverage. The description adds no additional parameter-specific semantics beyond what the schema offers. The examples illustrate usage but do not clarify parameter behavior further. Thus the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource combination: 'Scan projects for known security vulnerabilities (CVEs)', clearly stating the tool's core function. It names the underlying audit tools (npm audit, etc.), which adds specificity. However, it does not explicitly differentiate itself from sibling tools such as depsonar_cve or depsonar_live_cve, which likely also deal with CVEs, so it misses the sibling-distinguishing criterion.

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

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

The description provides a clear trigger for when to use the tool: 'CRITICAL: Run this after any CVE announcement (e.g. Svelte CVE-2026-22775, devalue DoS).' This gives explicit contextual guidance. It also includes example user queries, helping an agent recognize valid use cases. However, it does not specify when NOT to use it or point to alternative sibling tools, so it stops short of full exclusions/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 read-only, idempotent, and non-destructive behavior. The description adds valuable context by specifying the nature of the output (version breakdown, changelog URLs, release notes) and its purpose as a pre-update check, going beyond the structured annotations.

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

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

The description is front-loaded with a clear purpose and usage directive, followed by helpful examples. It is slightly longer than strictly necessary due to the example list, but every section earns its place and structure is logical.

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

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

Given a single-parameter tool with no output schema, the description thoroughly covers what the tool does, what it returns, and when to use it. The inclusion of examples and the explicit ordering relative to depsonar_update makes it self-sufficient 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?

The input schema already fully describes the single 'project' parameter as 'Project name or path' with 100% coverage. The description's examples (e.g., 'RoomPilot', 'my project') illustrate usage but do not add new semantic meaning 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 uses a specific verb ('Check') and resource ('changelogs and breaking changes'), clearly distinguishing it from sibling tools like depsonar_update. It also details the output (major/minor/patch breakdown, changelog URLs, release notes), making its purpose 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?

Explicitly states 'Run this BEFORE depsonar_update to understand what will change,' naming the alternative and establishing a clear usage order. The three examples further illustrate when to use the tool, from specific package queries to project-wide 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral details such as grouping results by ecosystem for Node projects and flagging major version updates, which are not implied by the schema or annotations, going beyond the baseline.

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 appropriately sized, with a clear first sentence, a list of supported ecosystems, two key behavioral traits, and two illustrative examples. Every sentence earns its place, and the structure is front-loaded with the core purpose. It is compact yet informative.

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

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

For a simple one-parameter read-only tool, the description is fairly complete: it explains the purpose, supported ecosystems, and specific behavior. While there is no output schema or mention of return format, the annotations and description together give sufficient context to use the tool effectively. Missing output details are a minor gap given the tool's simplicity.

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

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

Schema coverage is 100%, with the 'project' parameter fully described as a project name or absolute path. The description does not add any extra parameter-level detail, so the baseline score of 3 is appropriate because the schema carries the semantic weight.

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

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

The description clearly states the tool checks a project for outdated dependencies, using a specific verb and resource. It distinguishes from siblings by mentioning grouping by ecosystem and flagging major version updates, which is a unique behavior not implied by any other tool. The supported ecosystem list adds further specificity.

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

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

The description provides clear context for use through natural language examples ("Check JobPin for outdated deps") and mentions the supported ecosystems, implying when to use it. However, it does not explicitly state when not to use it or name alternative tools, though the examples effectively illustrate typical usage scenarios.

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

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

Annotations already indicate idempotent, non-destructive, and not read-only, which matches the 'view or update' description. The description adds value by specifying the configuration file location (~/.depsonarrc.json) and illustrating both operations. 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 brief and front-loaded with the primary action. The example usage adds practical clarity without redundancy. Every sentence serves a purpose, making it highly efficient.

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

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

With two simple parameters and no output schema, the description provides sufficient context: where config is stored, what actions are possible, and illustrative examples. It doesn't describe the exact output format for 'show', but that is a minor gap given the tool's simplicity and strong annotations.

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

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

Schema descriptions cover both parameters fully, so the baseline is 3. The description adds value by giving concrete examples ('Show depsonar config' and 'Set projects directory to ~/Code') that clarify how each parameter is used, going beyond the schema's field definitions.

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

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

The description states a specific verb and resource: 'View or update configuration.' This clearly distinguishes it from sibling tools like depsonar_scan or depsonar_alerts, which focus on other actions. The examples reinforce the intended scope.

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

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

The description clearly implies this is the tool for configuration tasks, with examples showing both viewing and updating. It doesn't explicitly exclude alternatives or mention when not to use it, but the distinct purpose and examples provide clear context, making it easy to choose this tool over 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the curated framework-specific database and the urgency after CVE announcements, which goes beyond the schema. There is no contradiction with annotations. It doesn't mention whether network access or updates are needed, but the annotations cover the safety profile.

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

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

The description is appropriately sized and front-loaded: the first sentence states the core purpose, the second differentiates it from npm audit, and the next line provides a critical usage trigger. The examples are concise and useful for an agent to recognize natural-language requests. 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 read-only check tool, the description covers purpose, scope, urgency, and example invocations. All parameters are documented in the schema, and annotations provide the safety context. The lack of an output schema is mitigated by the examples, though a brief note about the return format would improve completeness further.

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

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

The input schema already provides 100% coverage for all three parameters with clear descriptions. The tool description adds example usage like 'Show CVE database' which maps to show_db, but does not enrich the meaning of the parameters beyond what the schema already provides. Thus, baseline 3 is appropriate.

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

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

The description clearly uses a specific verb ('Check') with a resource ('projects') and a defined scope ('known framework CVEs' with a list of frameworks). It also differentiates itself from npm audit by saying 'Goes beyond npm audit.' However, it does not explicitly distinguish itself from sibling tools like depsonar_audit or depsonar_live_cve, so it stops short of a 5.

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

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

The description gives a strong, explicit usage trigger: 'CRITICAL after any CVE announcement. Run immediately when new CVEs are published.' This clearly states when the tool should be used. It does not mention when not to use it or suggest alternative sibling tools, which prevents 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 read-only, idempotent, non-destructive hints. The description adds valuable behavioral detail by explaining it checks both npm deprecated flags and a curated list of known replacements, which is beyond the annotation info.

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

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

The description is well-structured and front-loaded with the core purpose, but includes multiple example lines that could be condensed. The examples add value, so it remains concise enough without being bloated.

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 straightforward read-only nature and the absence of an output schema, the description sufficiently covers what is detected and provides concrete replacement examples. It does not explain return format, but that is not critical for this simple detection tool.

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

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

The input schema covers both parameters (project, directory) with 100% description coverage, so the description does not need to add parameter semantics. It does not meaningfully expand on the schema, warranting the baseline of 3.

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

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

The description uses a specific verb 'Detect' and identifies the resource (deprecated, unmaintained, or replaced packages). It distinguishes from sibling tools by focusing specifically on deprecation status via npm flags and a curated replacement list, unlike CVE or secrets tools.

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

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

The description provides example user queries but lacks explicit when-to-use guidance or exclusionary notes versus comparable tools like depsonar_audit or depsonar_check. It implies usage through examples but does not clearly state alternatives or when not to use.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by enumerating the ecosystems checked (node, python, ruby, etc.), which helps set expectations. No contradictory behavior is described.

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

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

The description is two concise sentences plus two illustrative examples. It front-loads the tool's purpose and supported image types without 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 read-only scanning tool with no output schema, the description provides sufficient information: it states the target files, the types of issues found, and the supported ecosystems. It doesn't describe the result format, but the examples imply a straightforward report, making it adequate for tool selection.

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

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

The input schema already fully documents both parameters (project and directory) with 100% coverage. The description does not add parameter-specific details beyond the examples, so it meets the baseline for schema-covered 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 uses a specific verb 'Scan' and identifies the resource 'Dockerfile and docker-compose files' with a clear objective ('outdated or EOL base images'). It also lists supported image types, which distinguishes it from generic depsonar_audit or depsonar_scan tools.

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

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

The description includes example user queries that should trigger this tool, such as 'Check my Docker images' and 'Any EOL images in my projects?', providing clear usage context. It doesn't explicitly compare to sibling tools, but its scope is well-defined.

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, so the safe profile is known. The description adds valuable context: fetches from GitHub + npm registry, offers readme/changelog/migration sections, and notes changelog covers 'last 5 versions'. It does not disclose rate limits or error behavior, but with annotation coverage, this is acceptable and adds source and data freshness context.

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

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

The description is moderately sized but well-structured with a front-loaded main sentence, bold section headers, and a clear examples list. Each sentence serves a purpose, though it could be slightly tightened without losing value. The use of bullet points and examples aids scannability.

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

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

With no output schema, the description does a good job explaining the tool's capabilities and available sections, but it does not explicitly describe the return format (e.g., markdown text). Given the tool's read-only, informational nature and the inclusion of examples, the description is mostly complete, though a note about output format would make it more 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 coverage is 100% with each parameter having a description. The description goes beyond schema by explaining what each section returns (e.g., 'readme: Latest README with API docs...') and provides concrete examples of query usage ('query="runes" for Svelte 5 migration docs'), thus adding meaningful semantic value beyond the raw 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 'Fetch up-to-date documentation, changelogs, and migration guides for any npm package directly from source', which is a specific verb+resource with clear scope. It distinguishes itself from sibling tools like depsonar_changelog and depsonar_migrate by covering all three sections and adding 'directly from source' as a unique source attribute.

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 context with 'Use this BEFORE writing code that depends on a library, to get the latest API docs and avoid hallucinating outdated APIs.' It also explains how to combine query and sections with examples, but does not explicitly name alternatives or when-not-to-use scenarios, which would push it to 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 readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe read. The description adds behavioral detail about what is validated (lockfile freshness, tsconfig, Svelte config), making the tool's scope more transparent. It does not contradict annotations or disclose side effects, but the annotation coverage reduces the need for more.

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 plus a list of examples, all relevant. It front-loads the purpose and provides concrete example queries. No filler or redundancy.

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

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

The tool has two simple optional parameters, no output schema, and good annotations. The description explains the validation scope and gives usage examples. It does not describe return format, but for a read-only validation tool this is acceptable.

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%: both 'project' and 'directory' have descriptions. The description does not add additional param semantics beyond the schema, so it relies on 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 'Validate project environments' and enumerates specific checks: .env/.env.example sync, lockfile freshness, tsconfig best practices, Svelte config, multiple lockfiles. This distinguishes it from sibling tools like depsonar_check or depsonar_audit, which focus on dependencies or 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 description provides context for when to use via example prompts like 'Check my project environments' and 'Any env issues in JobPin?', and implies this is for environment/config validation. However, it does not explicitly mention alternatives or exclusions compared to sibling tools, so it's clear but not fully explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by specifying the exact checks (outdated deps, security issues, lockfile) and the output scale (0-100). It does not contradict the annotations and provides useful additional context about what the tool evaluates.

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: a single action sentence followed by two clarifying examples. It front-loads the core purpose (0-100 score) and avoids redundancy, with every sentence earning its place.

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

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

The description is reasonably complete for a simple read-only tool with a single parameter. It explains what is checked, the output scale, and provides usage examples. A minor gap is the lack of detail on the return structure (e.g., whether scores come with a breakdown), but given no output schema, the description still covers the essential 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?

The parameter 'project' is fully documented in the schema with 'Project name (e.g. 'my-app') or full absolute path', giving 100% schema coverage. The description adds no additional parameter-specific guidance, so it stays at the baseline score of 3 as the schema already carries the semantic burden.

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

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

The description clearly states the tool scores a project from 0-100 and lists what it checks (outdated deps, security issues, lockfile), making the purpose specific and unambiguous. The included examples further clarify the intended use case, distinguishing it from sibling tools like check or scan by focusing on an overall health score.

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

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

The description provides clear context via natural-language examples ('How healthy is JobPin?') showing when users would invoke this tool. However, it does not explicitly mention alternatives or exclusion criteria compared to sibling tools, so it lacks the 'when-not-to-use' guidance for 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 read-only, idempotent, non-destructive behavior. The description adds that the command combines multiple check types and optionally skips dependencies, but does not detail output format, runtime, or other behavioral nuances. This aligns with a baseline score given strong annotations.

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

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

The description is concise, front-loaded with the main purpose, then lists components, provides a clear usage statement, and includes three illustrative examples. No unnecessary words.

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

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

For a read-only aggregate tool with no output schema, the description covers purpose, components, and usage context well. It lacks only an explicit note on potential performance/scope implications of running everything, which would make it fully complete.

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

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

Input schema has 100% coverage with descriptive parameter names and descriptions. The description adds a comment about 'optionally dependency scan' which maps to skip_deps, but adds no other parameter-level meaning 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 states a clear verb ('health check'), resource ('infrastructure'), and scope ('complete', 'in one command'), and explicitly positions itself as the 'run everything' command, distinguishing it from specific sibling tools like depsonar_runtimes and depsonar_cve.

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

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

It explicitly says to use when you want a full picture and provides examples, giving clear context. However, it does not explicitly mention alternatives for targeted checks or when not to use this tool, so it stops 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?

The description discloses that clean=true 'nuke node_modules/vendor first', which is a meaningful behavioral detail beyond what the annotations say (idempotentHint=true, destructiveHint=false). It clarifies the destructive nature of the clean option. No annotation contradiction exists. However, it doesn't mention other traits like network usage or lockfile handling, so a small gap remains.

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 short sentences plus two examples. Every word earns its place. The examples illustrate both primary use cases (basic install and clean install) efficiently. No fluff or repetition.

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

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

For a simple two-parameter tool with no output schema, the description is nearly complete. It covers the main behavior (install dependencies), the optional clean flag, and provides examples. It could mention that project can be a path (schema already covers this) or state what happens after install (e.g., success message), but those are minor gaps given the low complexity.

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

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

Schema coverage is 100% (both parameters documented), so baseline is 3. The description adds value by explaining clean=true in natural language ('nuke node_modules/vendor first') and showing usage via examples for 'project'. It clarifies the practical interpretation of the parameters beyond the schema's terse 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 resource ('dependencies') and verb ('install') via the title and examples. The examples 'Install deps for JobPin' and 'Clean install my project' unambiguously show the tool installs dependencies for a project. It distinguishes from siblings like depsonar_update and depsonar_check by focusing on fresh installs.

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

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

The description implies usage (fresh install, clean install) through examples, and mentions when to use clean=true. However, it does not explicitly contrast with alternative tools like depsonar_update (for updating existing deps) or state when not to use this tool. The 'fresh install' phrasing hints at intent but lacks explicit exclusion or 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=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is known. The description adds value by detailing behavioral specifics: exactly which license types are flagged and why (e.g., copyleft requires source disclosure). 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 concise and front-loaded with the core purpose, followed by a bullet list of flags and examples. Every sentence serves a purpose, though slightly informal phrasing prevents a perfect 5.

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 only 2 optional parameters and no output schema, the description is fairly complete: it defines the tool's scope, flags specific license types, and gives example user intents. It does not mention the exact return format, but the examples imply a report/answer-style output, making it 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?

The input schema provides 100% coverage with clear descriptions for both parameters: 'project' and 'directory.' The description's examples add some context but no additional parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Check dependency licenses for commercial/SaaS compatibility.' It lists specific license types it flags (GPL/AGPL, non-commercial, unknown), which distinguishes it from sibling tools like depsonar_cve or depsonar_deprecated.

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 context for when to use it ('Important for SaaS products to avoid legal issues') and includes examples of user queries. However, it does not explicitly mention when not to use it or contrast with overlapping tools like depsonar_audit, so it's clear but lacks 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 convey read-only, idempotent, and non-destructive behavior. The description adds that it queries an external live API (network dependency) and supports specific package managers, 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 core description is three sentences and front-loaded with purpose and differentiator. The example block is helpful but somewhat redundant; overall it's concise without unnecessary 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 moderate-complexity tool with good schema and annotations, the description covers purpose, alternative, and ecosystem support. It lacks output or failure details but those are not critical for this scan tool.

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

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

The input schema describes both parameters clearly with 100% coverage, so the description doesn't need to add much. It does not provide syntax or format details beyond the schema, but the baseline of 3 is appropriate.

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

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

The description opens with 'Real-time vulnerability scan using the osv.dev API' – a specific verb and resource. It lists supported ecosystems and explicitly contrasts with depsonar_audit, distinguishing it from siblings.

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

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

Clearly states when to prefer this tool over depsonar_audit by contrasting live vs local audit. Also notes no API key needed, providing actionable decision criteria 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description aligns by describing scanning/detection rather than mutation. It adds useful behavioral context beyond the annotations: it scans code, returns exact file locations, provides migration instructions, and currently supports only specified framework upgrade paths.

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

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

The description is front-loaded with a clear one-sentence purpose, followed by a compact paragraph on output details and a short list of examples. Every sentence contributes either capability, supported scope, or usage illustration; there is no filler or redundancy.

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

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

With no output schema, the description compensates by explicitly stating the return value: 'Finds exact file locations... with migration instructions for each pattern.' It also discloses supported framework versions and provides example prompts, making the tool's behavior fully understandable for a read-only detector.

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?

Both parameters (project, directory) are fully described in the input schema (100% coverage), so the description need not repeat their syntax or meaning. The examples reinforce that project is optional ('all projects') but add no new 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 opens with a specific verb-resource pair: 'Detect framework migration needs by scanning code for deprecated patterns.' It lists supported migrations (Svelte 4→5, Next.js 13→14→15) and includes concrete usage examples, clearly distinguishing it from broader scanner tools like depsonar_scan or depsonar_deprecated.

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 examples ('Check if my projects need Svelte 5 migration', 'Migration scan for all projects') establish clear use cases for the tool. However, it does not explicitly state when to avoid this tool or how it compares to sibling tools such as depsonar_deprecated, so it stops short of full exclusion guidance.

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

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

Beyond annotations (read-only, idempotent), the description adds meaningful behavioral detail: it checks both installed runtime versions and project version files, and detects EOL/outdated versions. This helps the agent anticipate the tool's operational scope without contradicting 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 concise and front-loaded: a clear purpose statement, a scope sentence, and a concise examples block. Every sentence earns its place without fluff, making it easy for an agent to parse quickly.

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 check tool with no output schema, the description covers the key behaviors, target languages, project files, and example intents. It could be slightly more explicit about response/result format, but the examples and scope make it sufficiently complete.

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

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

The input schema already has 100% description coverage for all three parameters. The description adds only indirect context through examples, not additional syntax or meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Check installed runtime versions' with an explicit list of languages (Node.js, Python, Rust, etc.). It clearly distinguishes itself from sibling tools by focusing on runtime version detection and project version files, with concrete example queries.

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 user-facing example phrasings ('Is my Node.js up to date?') that clearly imply when to invoke this tool. It doesn't explicitly mention alternatives or exclusions, but the examples sufficiently convey the intended usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds valuable behavioral context: it auto-detects language and framework and supports filtering, which are useful traits 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 with the main action, followed by capability and examples. Every sentence earns its place, and the examples are practical and helpful.

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?

There is no output schema, and the description does not explicitly state what the scan returns (e.g., a status report, dependency list, or vulnerabilities). The examples imply 'status', but the response format remains unclear, which is a gap 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 100%, with each parameter having a clear description. The description reinforces filtering by language/framework but does not add extra meaning beyond the schema, such as the default behavior of the 'directory' parameter.

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

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

The description clearly states the tool's purpose: 'Scan all projects in your workspace' with specific verb and resource. It also mentions auto-detection of language/framework and filtering, distinguishing it from siblings like depsonar_check or depsonar_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?

The description gives clear context for use (scanning all projects or filtering by language/framework) and provides example prompts. However, it does not explicitly mention alternatives or when not to use this tool relative to the many sibling tools, leaving some ambiguity.

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 non-destructive behavior. The description adds that the npm registry is the external source and that results include specific fields, but it does not disclose pagination, rate limits, or result ordering/caveats.

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: a purpose sentence, a usage sentence, and three illustrative examples. Every part adds value without redundancy, and the key 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 one-parameter search tool with strong annotations and a stated return shape, this is nearly complete. It could optionally mention pagination/limits or no-results handling, but the current description sufficiently enables correct selection and invocation.

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

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

The single 'query' parameter is 100% covered by the schema, so the baseline is 3. The description's examples ('Search for Svelte authentication libraries') demonstrate full natural-language phrasing, complementing the schema's keyword-style examples and enriching how the agent should interpret the parameter.

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

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

The description uses a specific verb ('Search') on a specific resource ('npm registry') and explicitly states the return fields (name, latest version, description). It also distinguishes itself by positioning as a precursor to depsonar_docs, setting it apart from 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?

Explicitly tells the agent when to use this tool ('find the right package name before calling depsonar_docs') and provides natural-language example queries. It does not enumerate exclusions or alternatives beyond depsonar_docs, but the context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by detailing what it detects (AWS keys, GitHub tokens, etc.) and that it also 'checks that .env files are properly gitignored,' which is not derivable from annotations. This goes beyond minimal scoping and enriches the tool's behavior.

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

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

The description is well-structured with a clear purpose statement, a list of detected secret types, an additional .env check, and usage examples. It is slightly verbose but every sentence adds value. The examples are practical and aid understanding without unnecessary padding, though it could be tightened slightly.

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 scanning tool with two optional parameters and no output schema, the description covers the main use case and expected behavior. It names specific secret categories and the .env gitignore check, giving a good sense of what the tool does. It does not describe return format, but the absence of an output schema and the straightforward nature of the tool make this 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 coverage is 100%, with both parameters ('project' and 'directory') already described in the input schema. The description does not add any additional parameter semantics beyond what the schema provides. Per the rubric, a baseline of 3 is appropriate when schema does the heavy lifting, and there is no extra detail to raise the score.

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: 'Scan project files for exposed secrets, API keys, tokens, and credentials.' It lists specific secret types and distinguishes itself from sibling scanners like depsonar_cve or depsonar_licenses by focusing on secrets. The verb 'scan' and explicit resource 'project files' make the purpose unambiguous.

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

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

Usage is implied through examples like 'Scan my projects for exposed secrets' and 'Any leaked API keys in JobPin?', which indicate user intents that map to this tool. However, the description does not explicitly mention when not to use this tool or name alternatives, so the guidance remains implicit rather than explicit.

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

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

The description discloses platform-specific behavior (launchd on macOS, cron on Linux), writes results to ~/.depsonar-cache.json, and notes zero RAM/tokens/cost between runs. This goes beyond the annotations (e.g., idempotentHint) and gives the agent a realistic picture of side effects. No contradiction with annotations.

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

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

The description is well-structured: first sentence defines the action, then platform notes, then operational details, then result location, and ends with concrete examples. Each sentence earns its place with no redundant 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 setup tool with two optional parameters, the description covers the operation's lifecycle, platform variations, the cache file, and integration with depsonar_alerts. It does not explain return values (no output schema), but that is not a major gap for this tool. It is sufficient 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%, so the baseline is 3. The description adds value by embedding usage in examples ('Check my deps every 12 hours' maps to interval_hours, 'Remove the background checker' maps to uninstall), making the parameters more concrete than the schema alone.

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 'Install or remove the background dependency checker,' which is a specific verb+resource statement. It distinguishes this tool from siblings like depsonar_check (which likely runs an immediate check) by emphasizing background/scheduled execution. The examples further clarify the purpose.

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 examples like 'Setup background dependency checking' and 'Remove the background checker,' making it clear when to invoke the tool. However, it does not explicitly state when not to use it or compare with alternatives like depsonar_check, so it earns a 4 rather than 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?

Beyond the readOnlyHint and idempotentHint annotations, the description explains that it compares installed versions against latest and shows update commands, which is useful behavioral context. This adds meaningful information about the tool's output without contradicting any annotations.

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

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

The description is well-structured and appropriately sized: a clear purpose statement, a useful list of supported tools, a concise summary of output, and practical examples. Every sentence adds value and the most essential information appears first.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately explains what the user will see (installed vs latest, update commands). It also provides usage examples, making the tool's behavior sufficiently complete for an agent to select and invoke it.

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

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

The single parameter 'category' is fully described in the schema with clear allowed values, and the schema description coverage is 100%. The main description does not add extra meaning about parameter usage, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Check versions') and a clear resource ('globally installed tools'), listing the exact tools covered. This clearly distinguishes it from sibling tools like depsonar_check or depsonar_runtimes by scoping to global toolchain versions.

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

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

The description provides clear context for when to use the tool through natural language examples like 'Check my global tools' and 'Is pnpm up to date?'. However, it does not explicitly exclude situations or point to alternative tools, so it stops short of full when-not guidance.

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

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

The annotations already indicate this is not read-only and not destructive, but the description adds meaningful behavioral context by explaining the safety implications of each level: 'patch' is safest, 'latest' includes major breaking changes. This goes beyond the structured annotations and helps the agent understand the mutation's impact.

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

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

The description is concise and well-structured: it opens with a clear purpose statement, then lists the three safety levels in a scannable format, followed by concrete examples. Every sentence contributes useful information, with no fluff or redundant repetition of the tool name or schema.

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 mutation tool with four parameters and no output schema, the description provides sufficient context: it covers the project, level, packages, and dry-run via examples and safety level explanations. It does not describe return values or error scenarios, but given the absence of an output schema and the relative simplicity of the tool, it is reasonably complete. The only minor gap is lack of distinction from depsonar_update_all.

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

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

The input schema has 100% coverage, so baseline is 3. The description enhances understanding by providing natural-language examples that map to parameters (project, packages, level), such as 'Update svelte in Showly to latest', which illustrates how the level and package parameters are used together. This adds value beyond the schema's individual parameter 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: 'Update dependencies for a project' and specifies it works with any supported language. It is specific about the verb and resource, but does not explicitly differentiate it from sibling tools like depsonar_update_all, which likely handles bulk updates. Thus it is clear but lacks sibling differentiation.

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

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

The description provides usage context through the three safety levels (patch, minor, latest) and examples, implying when each level is appropriate. However, it does not explicitly state when to use this tool versus alternatives like depsonar_update_all, nor does it mention any exclusions or prerequisites. Guidance is present but primarily implied.

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 (which already indicate a mutating, non-destructive tool), the description adds the critical default behavior: 'Defaults to dry_run=true (safe preview)'. This is valuable context not present in structured fields. However, it does not discuss reversibility or post-update changes.

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, front-loaded with the core action, and uses three clear examples to illustrate usage. Every sentence adds value; no fluff or repetition.

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

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

No output schema exists, so the description should clarify expected outcomes. It covers the default dry-run, filtering, and examples, but does not explain return values, behavior when no projects match, or what happens when changes are applied. Given the tool's batch scope, more completeness would be helpful.

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 mentions filtering by framework or language, which aligns with the schema descriptions for those params. Schema coverage is 60%, leaving 'level' and 'directory' unexplained. The examples imply 'apply changes' means dry_run=false, but this mapping is not explicit.

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 'Batch update across all projects' with a specific verb and resource. It distinguishes itself from the sibling 'depsonar_update' (single project update) by emphasizing the batch scope. Examples reinforce the purpose.

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

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

The description provides clear context for when to use this tool (updating all projects) and shows filtering by framework/language. It does not explicitly mention alternatives or exclusions, but the name and sibling tools imply that 'depsonar_update' is for single-project updates.

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