DepFeed

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

The description adds useful behavioral context beyond annotations: it promises a compact response, and explicitly warns that if the package isn't covered, the agent should trust the structured NotCovered response rather than guessing. However, the inaccurate 'npm package' scoping introduces a misleading limitation, which reduces trust in the description's accuracy. Annotations already cover read-only/idempotent safety, so the added behavior is limited but relevant.

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 with no fluff. The first sentence states the core purpose, the second gives usage context, and the third provides a crucial edge-case instruction. Information is front-loaded and each 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?

The description covers purpose, usage, and a special case (NotCovered), and the output schema handles return details. However, the inaccurate 'npm package' scoping creates a gap: an agent may not discover it supports other ecosystems and could misuse the tool or choose the wrong one. Given the tool's complexity (multi-ecosystem, optional parameter), this inaccuracy leaves the description incomplete.

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% parameter coverage, so the description doesn't need to explain each parameter. However, the description's claim that it work with 'npm package' is narrower than the schema's ecosystem enum (npm, pypi, cargo, etc.), which could mislead an agent into thinking the tool is npm-only and not populating the ecosystem parameter correctly. This active contradiction with the schema lowers the value of the description's semantic contribution.

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 only the breaking changes for a package between two versions' and emphasizes compactness. It distinguishes from siblings by explicitly naming get_package_updates as an alternative. However, it unnecessarily restricts to 'npm package' while the schema supports multiple ecosystems, slightly misrepresenting the tool's 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 provides strong when-to-use guidance: 'Use this instead of get_package_updates when the only question is "will upgrading from X to Y break something"'. It even gives a concrete example ('right before running an upgrade command'). However, the 'npm package' phrasing may mislead usage for non-npm ecosystems, which the schema explicitly supports, so it's not fully accurate.

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 and idempotent, but the description goes further by detailing how to interpret the 'overall' field, treating 'insufficient_data' like 'incompatible', and warning never to guess compatibility from training knowledge. This is substantial 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 longer than the two-sentence ideal but every sentence earns its place: function, usage, output interpretation, and a warning. It is front-loaded with the core purpose and organized logically, though slightly verbose.

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 check tool with output schema, the description is nearly complete: it explains purpose, usage, output interpretation, and per-pair details. The only gap is not mentioning the 'ecosystem' parameter for non-npm ecosystems, but the schema covers that.

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 100% coverage with descriptions for both parameters. The description adds value by clarifying that 'node' can be a package name and giving a working example (react/next), plus the underlying compatibility mechanism. This exceeds the baseline but doesn't fully redefine parameter semantics.

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

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

The description clearly states the tool checks mutual compatibility of npm packages based on peerDependencies/engines, with a concrete example. It explicitly distinguishes from sibling get_package_updates by explaining a package can look fine alone but conflict with peers, making the tool's unique 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 says to call this before recommending or performing a multi-package upgrade, not just a single get_package_updates call. Names the alternative and explains why it's insufficient, giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond readOnlyHint and idempotentHint annotations, the description adds critical behavioral details: on deprecated/retired it returns recommended_successor and source_url, and it explains the NotCovered meaning (not tracked, not confirmed active). This helps the agent interpret responses correctly and avoid pitfalls.

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

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

The description is four sentences, each carrying substantive information: core action, use case, response details, and an important caveat. No redundancy, front-loaded, and well-organized.

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 the tool's purpose, when to use it, response semantics, and edge cases (NotCovered). With an output schema present, return values do not need to be detailed, and the description is complete for practical agent 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 100%, so baseline is 3. The description adds value by specifying the vendor scope and clarifying that an unlisted model_id returns NotCovered, which informs parameter value expectations and response interpretation.

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 whether an AI model_id is active, deprecated, or retired, specifying the vendor scope (Anthropic, OpenAI, Google). This distinct verb+resource combination distinguishes it from sibling tools focused on packages and 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?

The description gives a clear use case: use before hardcoding or recommending a model_id in code, such as when pinning a specific model string. It does not explicitly mention when not to use it or name alternatives, but the context is unambiguous.

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 (destructiveHint, idempotentHint), the description adds crucial behavioral details: scoping to the caller's own key and the exact return value (deleted:false) for both foreign and unknown ids. This is valuable context not derivable from annotations or schema.

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, action-first structure, and every clause adds value. No redundancy or extraneous information.

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

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

For a simple one-parameter destructive tool, the description is complete: it covers plan restriction, key scoping, idempotent behavior, and the return value for edge cases. An output schema exists, so return details beyond the mentioned deleted:false are not needed.

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

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

The schema already fully documents the id parameter (100% coverage). The description adds the useful detail that the id comes from list_webhook_subscriptions or the register call, which helps the agent know how to obtain a valid value.

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 action ('Deletes one of the caller's own webhook subscriptions by id') with a specific verb and resource. It distinguishes from siblings like register/list by specifying deletion and the source of the id.

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 the tool: 'stop deliveries to a decommissioned endpoint, or after status:"failing" shows a target has been unreachable past the retry cap.' Also notes the Team plan restriction, giving clear context for appropriate 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses determinism, data source (shipped .d.ts and package.json/LICENSE), and the critical edge case where packages without bundled types return NotCovered with 'no_types' rather than an empty, misleading diff. The warning against guessing from training knowledge adds significant transparency.

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?

Five sentences, each earning its place: output shape, usage scenarios, determinism/source, NotCovered edge case, and a trust directive. No redundancy and well front-loaded with the core output.

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 both the primary output (diff symbols + flags) and the NotCovered fallback, covering edge cases, data provenance, and a trust guideline. With an output schema present and this rich description, the agent has full context for correct invocation.

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

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

Input schema covers all five parameters with meaningful descriptions, so baseline is 3. The description adds context about 'npm package' and TypeScript symbols but does not provide parameter-level syntax or format details 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?

Description clearly states the tool returns the exact TypeScript export-level diff (removed/changed_signature/added symbols, with printed signatures) and a flags array of manifest-level changes. The 'Use this when' clause distinguishes it from broader upgrade/compat tools, and the detailed NotCovered behavior prevents confusion.

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 scenarios: 'Use this when a compiler error after an upgrade points at a specific symbol, or before an upgrade to catch a format/license/engines/install-script change a changelog often doesn't call out explicitly.' Also instructs to trust NotCovered over guessing. Does not name alternative tools or explicit 'when not' conditions, so 4 rather than 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 readOnly/idempotent/non-destructive annotations, the description explains the data source (endoflife.date), the default behavior when no cycle is given (most recent), and the structured NotCovered response with alternative suggestions. This gives the agent clear expectations without contradicting annotations.

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

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

The description is four sentences long, with the core purpose stated first and each subsequent sentence adding distinct value: source, distinction from sibling, cycle behavior, and handling of uncovered cases. No wasteful or redundant text.

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 that the tool is a read-only status lookup with a well-defined output schema and robust annotations, the description covers all necessary edge cases: what the tool does, when to use it, how to use it, and what to do when data is missing. The presence of an output schema further reduces the need to describe return values, so the overall description is 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 describes both parameters (product and cycle) with 100% coverage. The description adds valuable behavioral nuance: omitting cycle returns the most recent release cycle, while passing a cycle checks a specific major version. This extra context justifies a score above the baseline for high schema coverage.

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

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

The description clearly states the tool returns vendor end-of-life status for a runtime/framework product, with examples (node, python, ubuntu). It explicitly distinguishes itself from the sibling get_maintenance_status, so there is no ambiguity about its 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?

Provides explicit when-to-use guidance by differentiating from get_maintenance_status, and explains when to provide a cycle versus omit it. Also instructs how to handle uncovered products or cycles by trusting the NotCovered response rather than guessing.

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?

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds crucial behavioral details: it never guesses the status, returns 'unknown' when no release timestamp exists, and returns a structured NotCovered response with alternatives rather than relying on training knowledge. This goes well 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 dense but every sentence adds value. It front-loads the core purpose, then explains return values, edge-case behavior, and alternative tools. There is no filler or redundancy, making it efficient despite its length.

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 output schema exists and annotations are rich, the description still covers essential context: the meaning of each return value, the NotCovered fallback, and when to use sibling tools. It fully equips an agent to decide when and how to invoke the tool without requiring additional information.

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

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

The schema already provides 100% coverage for parameter descriptions (package and ecosystem with enum). The description adds semantic context by clarifying 'package' refers to a dependency (not a runtime/framework), which helps the agent avoid passing a runtime like Node.js to this tool. This extra nuance justifies a score above the baseline.

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 answers 'is this package still actively maintained' and specifies its output values ('active', 'stale', 'unknown'). It explicitly differentiates from related tools like get_eol_status and get_package_health, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'use this when choosing or replacing a dependency, not when upgrading one you already use.' It also names alternatives (get_eol_status, get_package_health) and explains the different questions they answer, giving clear usage criteria.

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?

While annotations already declare readOnlyHint=true and idempotentHint=true, the description adds essential behavioral context: it returns only curated, vendor-published sources (never a self-generated plan), explains the meaning of an empty 'recipes' array (tracked but no recipe for the exact jump) and explicitly instructs not to invent one, and clarifies how to handle NotCovered packages. These go well beyond the annotation basics.

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?

Four sentences, each serving a distinct purpose: the core definition, when to use it, behavior for empty results, and behavior for uncovered packages. Front-loaded with the main purpose, no filler, and 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?

The description covers purpose, when to use, edge-case semantics (empty recipes array, NotCovered response), and fallback behavior. With an output schema present, it doesn't need to detail return values, but it does explain the meaning of the structured response boundaries, making it fully sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all four parameters described in the schema. The description adds a concrete example ('e.g. next 14 to 15') and clarifies the 'major-version jump' semantic, which is not explicitly in the schema. This adds modest value beyond the schema, so slightly above baseline.

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 ('Returns') and resource ('official, vendor-published migration path codemod command and/or upgrade guide link') for a major-version jump of an npm package. It clearly differentiates from sibling tools by stating it should be called after check_compatibility or get_package_updates flags a breaking upgrade, and mentions falling back to get_package_updates.

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 this tool: 'Call this right after check_compatibility or get_package_updates flags a breaking major upgrade, before writing manual migration steps yourself.' It also provides clear alternatives: fall back to get_package_updates when the recipes array is empty, and trust the NotCovered response instead of guessing.

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 and idempotent behavior. The description adds critical context: the signal is an external aggregated judgment (deps.dev/OpenSSF), marked as is_external_signal, never DepFeed's own assessment, and the NotCovered response behavior. 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?

Three sentences, each earning its place. Front-loaded with the primary action, then key relationships and edge-case behavior. No redundancy or 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?

With an output schema present, return values are covered. The description addresses external-source semantics, NotCovered behavior, and sibling relationship, making it complete for an agent to confidently invoke the 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?

Input schema has 100% description coverage, so baseline is 3. The description does not add much parameter meaning beyond schema; however, it slightly narrows the scope by saying 'npm package' even though ecosystem supports multiple, which could be mildly misleading. Schema itself documents params well.

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 an npm package's OpenSSF Scorecard signal from deps.dev, enumerating specific checks (code review, branch protection, etc.). It distinguishes itself from sibling tools by naming get_maintenance_status as a complementary signal.

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 instructs to use both this tool and get_maintenance_status together, not one instead of the other. Also provides guidance for the NotCovered case, telling the agent to trust the structured response rather than guessing.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral detail: the on-demand ingestion flow for Pro/Team accounts (ingestion_status: 'in_progress' with retry_after_seconds), the extra quota cost, and the free-plan behavior with premium_feature hints. This goes far beyond the annotations and helps the agent predict what happens in edge cases.

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 information-dense with no filler. It is front-loaded with the core purpose, then covers usage context, edge cases, and quota implications in a logical flow. Every sentence contributes meaningful information without redundancy.

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

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

The description covers normal behavior, NotCovered responses, on-demand ingestion with retry timing, quota costs, and free-plan limitations. It also explains how to handle the response (call again after retry_after_seconds). The presence of an output schema offset the need to describe return values, and the description fills all other contextual 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?

The input schema already covers all 4 parameters with descriptions (e.g., package, ecosystem, max_tokens, since_version), so the baseline is 3. The description adds minimal parameter-specific detail beyond what the schema provides, and the schema already includes the 'changes strictly after' semantics for since_version.

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 clear statement of what the tool does: 'Returns categorized changes (breaking, security, deprecations, notable features) for an npm package since a given version, up to the latest known release.' This specifies the verb (returns), resource (npm package), and scope (since a version), and the categories distinguish it from generic update tools like get_updates_since.

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 says 'Use this before recommending or performing an upgrade of a dependency, to see what actually changed,' which gives a clear trigger for use. It also provides caveats such as trusting the NotCovered response and not falling back to general knowledge. However, it does not name specific alternative sibling tools, so it stops short of a full when/when-not comparison.

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. The description adds valuable context beyond annotations: each package resolves independently, one NotCovered/invalid-version result doesn't block others, and warns against guessing changes from training knowledge. This clarifies edge-case behavior not captured in schema or 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 efficiently structured. It front-loads the core purpose, then explains when to use it, and finally provides a key behavioral caveat. Every sentence earns its place with no redundancy or fluff.

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

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

Given the presence of an output schema and the batch complexity, the description covers the essential contextual points: the batch nature, the alternative to singular calls, and the critical independence of results. It also warns about trusting NotCovered, which is crucial for correct usage of the tool's 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by tying the packages parameter to real-world sources (package.json diff, lockfile upgrade) and explaining the independent resolution semantic, which goes beyond the schema's property 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 it is a batch version of get_package_updates, explicitly distinguishing it from the singular sibling. It uses a specific verb ('get') and describes the resource (package updates) and scope (multiple packages in one call).

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

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

It provides explicit when-to-use guidance (for a list of packages, e.g., dependency changes) and tells the agent to use this instead of the singular alternative to avoid N round-trips. It also gives clear behavioral instructions about independent resolution and trusting NotCovered results.

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, the description discloses that entries are LLM-classified (implying potential inaccuracy), that free callers receive an empty feed with an error code and upgrade_url, and explains cursor lifecycle. This adds meaningful context about expected 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 dense but well-structured, using a comparison to a sibling, then usage, then caveat and alternative, then plan restriction. No word is wasted; 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 the output schema exists, the description covers all necessary context: scope, usage pattern, classification caveat, alternative for actual vulnerabilities, and plan restrictions. It fully equips an agent to decide when and how to use the 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 schema already describes the cursor, but the description adds critical usage semantics: omit on first call, store and reuse the returned cursor. It also clarifies that omitting gets everything currently known. This enhances parameter understanding 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 explains this tool is a security-only feed restricted to category:security across all covered packages, distinguishing it from get_updates_since and get_vulnerabilities. The verb+resource is specific and the scope is explicit.

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

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

It provides explicit when-to-use context (CI/compliance automation), a clear alternative (get_vulnerabilities for verified advisories on one package), and notes the plan restriction with behavior for free/unauthenticated callers. This goes beyond basic usage.

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, non-mutating operation. The description adds valuable behavioral context beyond annotations: the cursor-based pagination flow, the fact that first call returns everything currently known, and the Pro/Team plan requirement with a specific error string and upgrade_url for free/unauthenticated callers. This is more than minimal added 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 compact and front-loaded with the core functionality. Each sentence adds meaningful information: what it returns, when to use it, the alternative, first-call behavior, and the plan restriction. No fluff or repetition of structured data.

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 paginated nature and the presence of an output schema, the description covers all essential contextual aspects: the across-packages scope, the cursor lifecycle, the category filter, the plan limitation with error handling, and the sibling alternative. The agent has enough information to select and invoke this tool correctly without overlooking any critical behavior.

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 documents both parameters fully with 100% coverage: cursor ('Cursor from a previous call. Omit to get everything currently known.') and category ('Restrict the feed to one category, e.g. "security" for a security-only digest.'). The description reiterates cursor semantics but does not add new parameter-level meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description opens with a clear verb+resource: 'Returns every change across all covered packages created since the given cursor, plus a new cursor for the next call.' It also distinguishes itself from the sibling tool get_package_updates, so the agent knows exactly what this tool does and what makes it unique.

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 usage guidance is provided: 'Use this for a recurring "what's new since I last checked" feed across the whole coverage set, not for a single package - use get_package_updates for that.' It also instructs on first call behavior (omit cursor) and subsequent calls (store and reuse the returned cursor), leaving no ambiguity about when and how to invoke this tool.

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

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

Annotations already mark this as read-only and idempotent, but the description goes further by clarifying interpretation of an empty advisories list: it means no known advisories, not that the package was unchecked, and directs the agent to the 'covered' field. It also warns against using training knowledge when the package is not covered. This adds real value 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 four sentences but each is information-dense, covering purpose, differentiation, fallback behavior, and interpretation of results. It is front-loaded with the core action, and no sentence is redundant. Slightly long, but appropriate for the tool's complexity.

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 output schema and annotations, the description still adds critical context: the source of the advisories, the distinction from the sibling tool, and the semantics of empty advisories and NotCovered responses. This makes it complete for an agent to decide when to invoke and how to interpret results.

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% and describes both package and ecosystem well, so the description doesn't need to repeat them. It adds the note that the tool checks 'one npm package' at a time, but this is minor since the schema already has a singular 'package' property. The description's mention of OSV.dev and the NotCovered response refers to output behavior, not parameter syntax, so the added parameter meaning is minimal.

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 action ('Returns verified CVE/GHSA security advisories') and resource ('one npm package'), plus source (OSV.dev), immediately clarifying what the tool does. It further distinguishes itself from the sibling get_security_digest by contrasting its verified OSV data with LLM-classified entries, so the purpose is unambiguous.

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

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

Explicit usage guidance is given: 'Use this to check one package for known vulnerabilities; use get_security_digest for a recurring feed across all covered packages.' It also tells the agent to rely on the structured NotCovered response when a package isn't covered instead of guessing, which is a clear directive.

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 adds meaningful behavioral details beyond the annotations: only ecosystems with at least one tracked package appear, the requested ecosystem is always present with an empty `packages` array if none yet, and runtime/framework products for get_eol_status are never listed. These are concrete behaviors that refine the readOnly/idempotent hints without contradiction.

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

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

The description is three sentences, each focused and non-redundant: main function, usage context, and parameter behavior with a namespace caveat. It is front-loaded with the core purpose and 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 one optional parameter, a rich output schema, and clear annotations (readOnly, idempotent, non-destructive, closed world), the description covers all necessary aspects: purpose, usage, parameter semantics, edge cases, and exclusions. An agent has enough context to select and invoke this tool correctly without guessing.

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

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

The schema description already covers the `ecosystem` parameter at 100%, but the tool description enriches it by explaining the exact result behavior when the parameter is provided (always present, empty array if none) versus omitted (all covered ecosystems). This goes beyond the schema's simple 'Limit the result' phrasing.

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 and resource: 'Lists every package this server currently tracks, grouped by ecosystem.' It also distinguishes itself from sibling tools by explicitly naming get_package_updates and get_eol_status, clarifying that this tool is for checking coverage rather than retrieving updates or EOL status.

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 explicit when-to-use guidance: 'Call this when unsure whether a package, or a whole ecosystem, is covered, instead of guessing or calling get_package_updates speculatively.' It also instructs when to pass the `ecosystem` parameter versus omit it, and notes the separate namespace for get_eol_status products, effectively providing exclusion criteria.

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 signal read-only, idempotent, non-destructive. The description adds valuable behavioral context: subscriptions are scoped to the caller's API key, the plan restriction with exact error string, and importantly that the signing secret is never returned after registration. This is genuinely useful beyond the annotations and no contradiction exists.

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

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

Two sentences, zero fluff. The first sentence states the core action and immediate use cases; the second covers plan restrictions and an important security caveat. All information is front-loaded and each clause earns its place.

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

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

For a no-parameter list tool with an output schema and solid annotations, the description covers purpose, use cases, plan behavior, error response, and a critical data omission (signing secret). It fully equips the agent to select and invoke the tool correctly. No gaps remain.

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 tool has zero parameters and the schema covers 100% of them by definition. The description adds no parameter syntax but clarifies the effective scope (caller's own API key), which is a reasonable complement given there is nothing otherwise to document.

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+scope: 'Lists every webhook subscription registered by the caller's own API key'. It clearly distinguishes this from the sibling 'register_webhook_subscription' and explicitly references 'delete_webhook_subscription' for the id use case. No ambiguity about what the tool does.

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: 'check what's currently registered before adding a duplicate' and 'find a subscription's id for delete_webhook_subscription'. It also provides a clear exclusion: Team plan only, with a specific error detail for free/pro callers. This goes beyond mere context and gives concrete 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 the readOnly/idempotent annotations, the description discloses how the plan is composed (from specific sub-tools each carrying a source_url) and the critical integrity rule that no step is invented without a real source, with a NotCovered response fallback. This is rich, non-obvious 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 dense sentences, each earning its place: purpose+composition, usage guidance, and data-integrity guarantee. No filler or repetition of schema fields.

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 complexity (composing multiple sub-tools), the description covers purpose, composition, source-traceability, edge-case behavior (NotCovered), and usage boundaries. The output schema and annotations fill remaining structural details, so nothing is left unexplained.

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 parameters are already well-documented. The description adds conditional semantics for related_packages ('if related_packages is given') and explains how it triggers check_compatibility, adding value beyond the schema's basic 'Other project packages to verify'.

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: 'Builds an ordered, source-backed upgrade plan for one npm package'. It also enumerates the composed sub-tools and distinguishes itself from the sibling check_breaking_changes, making the tool's role unmistakable.

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

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

Explicit usage guidance is provided: 'Call this when you're about to actually perform the upgrade yourself; call check_breaking_changes instead if you only want to know whether something breaks, without a plan.' This clearly states when to use this tool and when to prefer an 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?

The description reveals critical non-obvious behaviors: the response secret is returned only once at creation, the signature verification mechanism (HMAC-SHA256 of raw body), and the plan-entitlement error semantics differing from insufficient_data/NotCovered. These go far beyond the annotations, which only mark the tool as non-read-only, non-open-world, non-idempotent, and non-destructive, offering context the agent needs for correct invocation.

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

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

Three sentences, each densely informative: purpose and usage, plan restriction with error nuance, and the one-time secret with signature verification. The description is front-loaded, and no sentence is redundant or wasted.

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 that an output schema exists, the description need not detail return fields. It provides all essential contextual behavior: when to use, plan restriction, error shape, secret handling, and signature verification—everything an agent needs to invoke correctly and process the outcome.

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%: target_url is documented as an HTTPS endpoint and package as an optional npm package filter. The description does not add parameter-level meaning beyond this—it mentions signing and one-time secret, which relate to behavior/response, not parameter values. 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 states the tool's function with a specific verb ('Registers a URL'), identifies the trigger ('whenever DepFeed ingests a new change_entry'), and differentiates from the sibling get_updates_since by positioning it as an alternative to polling. The Team plan restriction is also explicit, making the purpose unambiguous.

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

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

Explicitly tells when to use ('use this once, when setting up push delivery') and directly names an alternative ('instead of polling get_updates_since on a schedule') with a rationale. It also clarifies the behavior for unsupported plans (free/pro callers get registered:false) and distinguishes this from other error shapes, providing clear usage guidance.

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

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

Annotations provide no hints (all false), so the description must carry the burden. It explains that feedback is recorded, how ratings work, and that reason/missing_info help DepFeed learn what to fix. It does not explicitly state that the operation is a write or that it won't modify other data, but the meaning is clear enough. It adds context beyond the annotations by explaining the purpose of the feedback loop.

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, each earning its place. It front-loads the primary purpose, then adds usage guidance and optional parameter rationale. No redundant or filler information.

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

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

With output schema present, the description doesn't need to explain return values. It covers the core purpose, when to use, rating scale, and optional field guidance. Given the simple nature of the tool (5 params, no nesting), the description is complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so all parameters have descriptions. The description adds extra meaning by emphasizing that reason and missing_info are 'especially valuable on a low rating', which is not in the schema. It also provides examples for tool_name. This goes beyond the schema's basic 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 purpose: 'Records feedback on how useful a previous DepFeed tool call was, as a 1-5 rating'. The verb 'records feedback' is specific, and the resource is 'a previous DepFeed tool call'. This tool is unique among siblings (all others are check/get/plan/register etc.), so it is easily distinguished.

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 guidance is provided: 'Call this after actually using another tool's result (e.g. get_package_updates, check_compatibility), once its usefulness is clear - not speculatively.' This clearly states when to use the tool and contrasts with speculative usage. It also gives guidance on optional parameters for low ratings, which is valuable.

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