Vigía

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

Beyond the readOnlyHint annotation, it discloses auth (none required), derivation (computed from registry publication dates), caching (one hour), and — crucially — coverage limits and exclusions (popular packages only, 0.x-to-0.y not reported as majors, calendar-versioned packages, pre-tracking deprecations). These constraints materially affect how an agent should interpret empty or partial results.

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 purpose and scope are front-loaded, and the dense parenthetical enumerations each carry distinct, load-bearing information rather than filler. It is a long block of prose, which costs a little readability, but nearly every 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?

With no output schema, the description carries the full burden of describing the return shape, and it does so item by item (version at cutoff date, new majors with first release dates, latest version, upgrade-guide link, runtimes ending within 180 days, AI models with prices). Combined with the stated coverage caveats, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so cutoff format, limit bounds and the ecosystems enum are already fully documented in the schema. The description restates what is returned rather than adding parameter syntax or defaults beyond it, so the 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?

States a specific verb and resource ('Returns what happened in software after a given date') and then enumerates exactly what is returned: new major versions across npm/PyPI/crates/Packagist, runtimes/frameworks released or ended, EOL windows, and AI model releases with prices. It explicitly distinguishes itself from sibling tools (upgrade_impact, package_status, eol_status) so an agent can route correctly.

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?

Gives explicit when-to-use ('once at the start of a coding session, passing the month your training data ends, or when you suspect a library you know has changed a lot') and names three alternatives with the conditions that select them. Nothing is left to inference.

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 declare readOnlyHint and openWorldHint, but the description adds substantial context beyond them: no authentication needed, nothing stored, a 300-dependency cap, a 40-live-resolution cap with not_resolved_yet/retry_after_s behavior, and the supported ecosystems. That is genuinely useful operational detail, though it does not quantify per-dependency latency or caching.

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?

Front-loaded with the purpose, then the return payload, then constraints and routing — a sensible order. It is somewhat dense and the 'Only npm and PyPI manifests are supported' line partially duplicates the ecosystem enum, but nearly every sentence carries weight.

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 carries the return-value burden and does so thoroughly: each status enum (up_to_date/outdated/outdated_major/unpinned/unsupported_spec), the summary-first ordering, deprecation, OSV IDs, and the unresolved-path behavior are all disclosed.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents the manifest content and ecosystem enum. The description only restates supported formats (package.json/requirements.txt), adding little syntactic or format detail 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?

States a specific verb and resource ('Audits a whole manifest in one call') and immediately distinguishes itself from siblings by naming package_status and version_status as the single-package/single-version alternatives. The scope (whole manifest, npm/PyPI only) 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?

Explicitly names when to use it ('when opening a project or before upgrading its dependencies') and routes to the correct alternatives ('For a single package use package_status; for one exact version use version_status'). No inference required.

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 only declare readOnlyHint=true, but the description adds substantial context the agent could not infer: no authentication required, status is recomputed on every call from today's date, upstream data from endoflife.date refreshes every 12 hours, and the result shape changes with the argument combination. The freshness/staleness caveat is exactly the kind of behavioral disclosure annotations cannot carry.

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?

Front-loaded with purpose, then coverage breadth, behavioral semantics, freshness, and usage — a logical order with no filler sentences. It is on the long side for a two-parameter tool, and the product enumeration list of ~18 example names could be trimmed, since the schema already gives aliases and the no-arg call lists identifiers.

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 carries the full burden of explaining return values — and it does, enumerating the four status values, release/active-support/EOL dates, days remaining or elapsed, and supported cycles. Combined with the authentication, freshness, and routing details, nothing an agent needs to invoke it correctly is missing.

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 per-parameter formats and aliases are already documented, but the description adds combinatorial semantics the schema does not express: product+version returns that cycle's status, product alone returns every release cycle, and neither argument lists all product identifiers. That mapping is genuinely useful, though it restates some schema content.

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?

Opens with a precise verb+resource ('Tells whether a language, runtime, framework, database or operating-system version is still supported') and scopes the domain to ~480 named products. It explicitly carves out its boundary against the sibling package_status ('for a library's own versions use package_status'), so an agent can route correctly without opening either schema.

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?

Gives concrete triggering scenarios — before choosing a runtime or base image, writing a Dockerfile or CI matrix, auditing an old version — and names the alternative tool (package_status) for the adjacent library-version use case. Both when-to-use and when-to-use-something-else are stated, not inferred.

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 openWorldHint, but the description adds real behavioral context: no authentication required, the full shape of the result (best version, incompatible newest release with reason, unverified constraints, per-constraint checks), and the transient requirements_not_synced_yet status with retry_after_s. This meaningfully exceeds the structured fields.

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?

Front-loaded with the core definition and scoping before the return-value detail and the alternatives. It is dense and long, but nearly every clause adds distinct information (constraint semantics, retry status, when-to-use, alternatives); a small amount of compression is possible.

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 carries the return-value burden and does so fully – best version, per-constraint checks, incompatible release plus reason, unverified constraints, and the transient status field. Combined with the when-to-use guidance and named alternatives, an agent has everything needed to select and call 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?

Schema coverage is 100%, so the baseline is 3, and the schema already documents all three parameters including the with-constraint format. The description adds semantic value by enumerating which runtime constraints are actually evaluated per ecosystem (npm engines/peerDependencies, PyPI Requires-Python, Rust rust-version, PHP require.php), which goes beyond the schema's examples.

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

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

States a precise verb+resource (finds the newest stable, non-withdrawn version of a package) with the key qualifier that the package's declared requirements must admit the given runtimes. It distinguishes itself clearly from siblings by naming package_status and eol_status and the conditions under which each is preferred.

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 gives the triggering scenario (a project pinned to an older Node, React, Python, Rust or PHP where the latest release may not support it) and names two alternatives with their own selection conditions (package_status for plain latest, eol_status for runtime support). Nothing is left to inference.

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 the description reinforces it with "Read-only and requires no authentication." It adds real behavioral context beyond annotations: a 15-result cap, popularity ordering, prefix-only matching against names, and catalog scope (~34,000 packages across npm, PyPI, crates.io, Packagist). Largely complete, though no note on pagination or how truncation past 15 matches is signalled.

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, front-loaded with the verb, matching rule and result shape before routing guidance. Every sentence carries distinct information — matching semantics, coverage scope, and routing — with no 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?

With no output schema, the description does the work of describing returns (up to 15 matches with ecosystem, name and popularity rank). Combined with the catalog scope and the prefix-only limitation, an agent can call this correctly; only the behavior when more than 15 packages match is left unstated.

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 both parameters are already documented, including the enum of ecosystems and the 1-100 character prefix constraint. The description restates prefix matching and ecosystem coverage without adding syntax, defaults, or edge cases the schema lacks. Baseline 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?

States a specific verb (searches), resource (catalog of tracked packages and AI models), matching mode (case-insensitive name prefix), result shape and ordering. It is immediately distinguishable from package_status, list_versions and model_status, which it names.

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 when-to-use ("when you do not know the exact package or model name before calling package_status, list_versions or model_status") plus an explicit when-not ("not a way to discover packages by what they do"). Routing to alternatives 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 readOnlyHint/openWorldHint, it discloses that no authentication is required and that untracked packages are fetched live on the first call — non-obvious side-effect behavior an agent should anticipate. It also maps withdrawal semantics per ecosystem (npm deprecated, PyPI/crates yanked, Packagist abandoned), which is behavioral context the annotations cannot convey.

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 output content, behavior disclosures and sibling routing are all front-loaded and each sentence earns its place. The first sentence is dense with field enumerations, but it is information the agent needs rather than 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?

There is no output schema, and the description compensates by enumerating the returned fields and the maintenance summary, plus the ecosystem-specific withdrawal vocabulary. Combined with the auth and live-fetch disclosures, an agent has everything needed to call and interpret the response.

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 ecosystem, name, limit and stable_only are already fully documented in the schema; the description adds no format or syntax details for them. Baseline 3 applies because the schema carries the parameter 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 names a specific verb and resource ('Lists the published versions of one package, newest first') and immediately enumerates the returned fields. It explicitly differentiates itself from siblings package_status and version_status, so an agent can route correctly without opening a schema.

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 gives three concrete use cases (judge release cadence, see which version was current at a date, check withdrawal status) and names both alternatives with the condition that selects each. Nothing is left to inference.

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 it discloses that no authentication is required, that prices are OpenRouter reference prices that may differ from a provider's direct pricing, that the catalog refreshes every 15 minutes, and how unknown ids are handled (similar-id fallback). These are exactly the operational caveats an agent needs and none are repeatable from 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?

Front-loads the resource and returned fields before modes and usage triggers, and every sentence carries distinct information. It is a dense single paragraph that runs long, but no sentence is 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?

With no output schema, the description compensates by enumerating every returned field (prices, context window, max output tokens, knowledge cutoff, modalities, retirement date, status enum values). Nothing needed to call or interpret the result is missing.

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 already 100%, so parameter syntax is covered; the description still adds semantic detail the schema lacks, namely that provider/query return up to 40 matches and that an unknown model_id yields a list of similar ids. The model_id precedence rule is stated in both places, so it is only mildly additive.

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?

Opens with a specific verb+resource ('Looks up AI models in the OpenRouter catalog') and enumerates exactly which fields are returned. It is clearly distinguishable from sibling tools like package_status or eol_status, which cover packages and end-of-life data rather than model catalog entries.

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?

Names four concrete triggers ('before writing a model ID in code, choosing between models, estimating costs, or checking whether a model is being retired') and an explicit exclusion ('It does not call, run or benchmark models'). The two invocation modes (single model_id vs. provider/query search) are also stated as conditions.

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/openWorldHint, the description discloses no-auth operation, a first-call live-registry fetch with a few-seconds latency cost, caching-implied 'not tracked yet' behavior, and the not_found_in_registry outcome plus similar-name suggestions. Latency and error semantics like these are exactly the context annotations cannot carry.

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?

Purpose is front-loaded and the routing alternatives come last, which is the right order. The middle return-field enumeration is dense and slightly run-on, but every item is substantive information that no output schema supplies, so little is 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?

With no output schema and only two parameters, the description must carry the return contract itself, and it does: every field of the result is named, including the error/status variants and the advisory and activity summaries. Nothing needed to call or interpret this tool is missing.

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% and the schema already documents both parameters with examples, enum values, scope syntax and the 'partial names are not accepted' constraint. The prose adds nothing further about name or ecosystem, so the 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?

States a specific verb+resource (returns the current state of one package) and enumerates exactly what that state includes: version, publish date, status, deprecation message, runtime requirements, license, advisories, activity. It is clearly distinguishable from version_status, upgrade_impact and find_package, which are named explicitly.

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?

Gives explicit use cases ('decide whether to add or recommend a package, or to learn its newest version') and then routes the agent away with four named alternatives tied to their triggering conditions (specific version → version_status; migration breakage → upgrade_impact; older runtime → find_compatible_version; unknown name → find_package). This is textbook when/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?

Annotations only carry readOnlyHint, so the description adds real behavioral context: no authentication required, newest-first ordering, the per-item shape, and the crucial limitation that history starts at Vigia's tracking start rather than being full release history. Auth and ordering are genuinely useful disclosures, though return format/pagination detail is absent and the read-only claim largely restates the hint.

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?

Front-loaded with the change taxonomy, then scope rules, then the alternative and use case. The opening enumeration of change kinds is dense but each item earns its place as disambiguation; overall it is slightly long but not padded.

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 describing item fields (entity, kind, old/new values, detection time). Combined with scope rules, the auth statement, the history limitation and the sibling reference, an agent has everything needed to call 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: how omitting name produces the global feed versus supplying ecosystem + name producing one entity's history. The enum values and limit bounds are left to the schema, which is fine.

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 (lists) and resource (changes Vigia detected) and enumerates the change kinds covered. It also distinguishes the tool's feed scope from list_versions, so an agent can tell it apart from siblings without opening a schema.

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 frames when to reach for it ('find out what happened after your training data ends, or whether a dependency or model has just changed') and names the sibling to use instead for full release history (list_versions). The scoping rule (no name = global feed; ecosystem + name = single-entity history) further pins down 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 only cover readOnlyHint and openWorldHint, and the description adds substantially more: no authentication required, a first-lookup latency of ~25 seconds, a 'pending' status with retry_after_s to poll, and the visibility limit that runtime-only exports without type declarations are not found.

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

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

The definition is dense but front-loaded: what it checks, then what it returns, then latency/retry behavior, then limits and usage. Every sentence carries information, though the single long first sentence is heavy to parse.

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

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

With no output schema, the description carries the return-value burden and does so fully (found flag, kind, signature, import module path, deprecation plus message, close-name suggestions), and it also covers latency, async retry, and applicability limits for a 4-parameter tool.

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

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

Schema description coverage is 100%, with each parameter (name, module, symbol, version) already documented including examples and version-resolution rules. The description adds no parameter-level syntax or constraint beyond that, so the 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?

States a specific verb and resource ('Checks whether an exported function, class, type or constant ... exists in a specific version of an npm package') and names the mechanism (TypeScript declarations). It is clearly distinguishable from siblings like find_compatible_version or version_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?

Gives an explicit trigger ('Use it before writing code that calls a library API you are not sure exists ... especially after a major upgrade') and routes to the alternative for a different need ('For a complete list of what changed between two versions use upgrade_impact'). Scope limits are also stated, so the agent knows when this tool will not help.

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?

Although annotations already declare readOnlyHint and openWorldHint, the description adds substantial context beyond them: no authentication required, ~25s first-request latency, a 'pending' status with retry_after_s and retry guidance, the types-only analysis method, and the blind spot for non-type behavior changes. It also describes the return shape (summary with counts and likely_breaking flag plus before/after detail).

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?

Front-loaded with the core action and method, then output shape, operational traits, limits, and finally alternatives. Every sentence carries distinct, load-bearing information with no filler despite the 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?

No output schema exists, yet the description explains the return contents (summary counts, likely_breaking flag, per-change before/after), the pending/retry flow, scope limits, and unsupported registries. An agent has everything needed to call and interpret 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 'from' and 'to' formats and the newer-than constraint are fully documented in the schema. The description adds the version-pair pairing concept but no syntax the schema lacks, so the 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 states a precise verb and resource ('Reports what changes between two versions of an npm package by diffing the public TypeScript API') and enumerates exactly what is diffed (exports, import paths, signatures, members, deprecations, engines/peerDependencies, changelog). This is immediately distinguishable from sibling tools like symbol_status or version_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?

It gives explicit use cases ('BEFORE upgrading a dependency across a major version, or when code written for an old version fails on a new one') and routes three alternative scenarios to named siblings: symbol_status for one API in one version, version_status for vulnerabilities, find_compatible_version for runtime fit.

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

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

Annotations already establish read-only and open-world, but the description adds materially: no authentication required, vulnerability data cached up to 6 hours, and explicit disclosure that the response signals when OSV could not be reached. This degradation/caching behavior is not derivable from the structured fields.

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?

Highly information-dense with no filler: the long opening sentence packs the full report surface, followed by auth/caching caveats and then routing guidance. The first sentence is a run-on with many comma-linked clauses, which slightly hurts front-loading, but every 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?

There is no output schema, so the description carries the full burden of return-value disclosure, and it does so thoroughly: existence, publish date, withdrawal semantics per registry, version-behind counts, and vulnerability fields including severity, summary, fixing version and nearest universal fix. Complete for a read-only query tool.

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

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

Schema description coverage is 100%, so the schema documents name, version and ecosystem, including the enum values and format constraints. The description restates the ecosystem list but adds no syntax or format guidance beyond what the schema already provides, so the 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?

States a precise verb+resource: reports on one exact version of a package across four named ecosystems, enumerating exactly what is reported (existence, publish date, withdrawn status, versions behind, vulnerabilities with fixes). It explicitly names sibling tools (package_status, check_dependencies) so an agent can distinguish scope without opening schemas.

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?

Gives concrete when-to-use triggers (before keeping, pinning or recommending a version; auditing one lockfile entry) and names the alternatives for adjacent jobs — package_status for latest/overall health, check_dependencies for whole-manifest audits. Nothing is left to inference.

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