Presend dependency checks

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

Substantially exceeds the annotations (readOnly/idempotent/openWorld/non-destructive). It discloses what is flagged (unseen human publisher after 180+ days inactivity in last 365 days), what is reported but explicitly not flagged (trusted OIDC publishing, pre-release, established handover), and a known blind spot (hijacked existing accounts). This is unusually rich behavioral disclosure.

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

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

Dense but mostly earned: every clause informs detection scope or output meaning, which matters with no output schema. One minor inefficiency is leading with the ecosystem caveat before stating the core purpose, but overall it is tight for the amount of behavior conveyed.

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 return-value explanation (found, first_published, package_age_days, new_package threshold) and detection caveats thoroughly. An agent has enough to call it correctly and interpret results for either ecosystem.

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 both parameters are described there, including the npm-vs-pypi split. The description largely restates the ecosystem semantics (npm full analysis, PyPI existence and age only) rather than adding syntax or format details beyond the schema, 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 names a specific analysis (publisher-change detection) and states precisely what is reported (found, first_published, package_age_days, new_package), plus the ecosystem scope. It is clearly distinguishable from siblings like typosquat_check or vulnerability_check by focusing on maintainer handover patterns.

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 clear context: npm-only for publisher analysis, PyPI limited to existence/age, and explicitly frames output as 'a heuristic for review, not proof.' It does not say which sibling to call instead when you need vulnerability or reputation data, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: GitHub-only scope and the failure mode that missing or private repositories return found: false.

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

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

Three tight sentences: purpose and output signals first, routing guidance second, scope and error behavior last. The field enumeration is informative rather than padding, and nothing is repeated across sentences.

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 appropriately discloses what comes back (the signal list) and how failures surface (found: false). Combined with annotations covering safety, 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?

Only one parameter, and schema description coverage is 100% (owner/name format with an example). The description restates 'owner/name' but adds no format or edge-case detail beyond the schema, 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 (maintenance signals for a GitHub repository) and enumerates the concrete signals returned: stars, forks, open issues, license, archived/fork flags, dates, topics. It is immediately distinguishable from siblings like vulnerability_check and typosquat_check.

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 the decision it supports ('judge whether a dependency looks maintained or abandoned') and names the alternative: for npm/PyPI packages without a known repo, use supply_chain_check. It also scopes the tool to GitHub only.

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

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

Annotations already declare read-only/idempotent/non-destructive/open-world, and the description adds substantial context beyond that: the package_not_found verdict, the 30-day new_package rule and review_recommended, the rule that failed checks become 'incomplete' rather than 'no_signals_found', and deprecated/yanked flagging. This is exactly the behavioral disclosure the annotations can't 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?

The actionable instruction is front-loaded and every clause adds a distinct behavior (not_found verdict, new-package threshold, unavailable_checks semantics). It is long and dense, but almost no sentence is filler; slightly heavy for 3 parameters.

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?

Though there is no output schema, the description explains the return semantics (overall_risk values, flags, version_checked, unavailable_checks) in enough detail that an agent can interpret the result. Nothing needed to call or act on the 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?

With 100% schema coverage the baseline is 3, but the description adds real semantic value: vulnerabilities are checked against the given version or the latest published one (version_checked/version_source), and it restates that maintainer_change_check is npm-only. Minor duplication of the schema rather than new meaning for 'package'.

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 ("One-call risk check") and enumerates exactly what it aggregates — vulnerability_check, typosquat_check, maintainer_change_check, repo_health_check — into a single verdict. It also distinguishes itself from the siblings by saying to use the individual tools to investigate one 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?

Explicit when-to-use ("Call this before installing or adding a package ... especially one whose name you recalled or that a model suggested") and an explicit alternative (the individual per-signal tools). The conditions that select this tool are 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the edit-distance threshold scales with name length, that names of 3 characters or fewer are not fuzzy-matched, that matching is against a curated popular-name list, and the important caveat that a clean result does not prove safety. These are exactly the behavioral limits an agent needs to interpret a negative result correctly.

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 short sentences, action guidance front-loaded, then mechanism, then limitations. Every sentence carries distinct information with no repetition of the name or title.

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

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

No output schema exists, so the description should ideally say what a positive/negative result looks like (matched name, distance, confidence). It covers meaning of a clean result and the non-existence gap, making it nearly complete, but the return shape is left implicit.

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 schema already documents both parameters, and the description adds no new per-parameter detail (format, casing, validation rules). The phrase 'whose name you typed or recalled' frames intent but does not enrich the parameter semantics. 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?

States a specific verb and resource ('checks whether an npm or PyPI package name is a near-miss of a well-known package (typosquatting)') and explicitly contrasts itself with the sibling supply_chain_check. An agent can distinguish it from the four other check tools without opening any 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 an explicit trigger ('Call before installing a package whose name you typed or recalled') plus an explicit exclusion and alternative ('It does not check that the package exists: supply_chain_check does'). This is textbook when-to-use / when-not-to-use routing.

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

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

Annotations already declare the safe read profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds genuinely useful behavior the annotations cannot convey: for npm/PyPI, a nonexistent package yields found: false and vulnerable: null rather than a clean result, which prevents a false negative reading.

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 tight sentences, front-loaded with purpose and capped by an explicit alternative. The ecosystem enumeration is mildly redundant with the schema's own ecosystem description, which is the only wasted verbiage.

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 usefully surfaces part of the return contract (found/vulnerable on missing packages). With annotations handling safety and the schema handling inputs, this is nearly complete; the only gap is that it never sketches the shape of a positive result.

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 three parameters are already documented in the schema. The description only restates the ecosystem list and the optionality of version ('optionally a specific version'), adding no syntax, format, or naming-convention detail beyond structured fields. 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 (checks) plus resource (a package/version) against a named backend (OSV.dev), and enumerates the supported ecosystems. It also distinguishes itself from the sibling supply_chain_check by naming it, so an agent can route 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?

The closing sentence gives an explicit alternative and the condition that selects it ('Use supply_chain_check for a combined verdict'). It stops short of stating when not to use this tool (e.g., typosquatting concerns belong to typosquat_check), so it is clear but not exhaustive.

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