UNPKG

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

Beyond the read-only, open-world, idempotent, non-destructive annotations, the description discloses that the tool checks live npm/UNPKG data, returns four classification categories with suggested URLs and an import map, and reports currentUsage as absent rather than falsely 'not detected' when scanning was skipped. This adds meaningful behavioral context not covered by annotations.

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

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

The description is front-loaded with the main purpose and then covers prerequisites and important edge cases in a logical order. It is somewhat long and repeats some return-category information that is also likely covered by the output schema, but the sentences generally earn their 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 tool's complexity, nested object parameters, live external data lookup, and the presence of an output schema, the description is complete enough for an agent to call it correctly. It covers data collection, runtime-only dependency filtering, scanning prerequisites, and the key behavioral consequence of not scanning.

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 actionable meaning beyond the schema: it specifies that the dependencies map must come from the project's package.json and must contain only runtime dependencies, never devDependencies. It also reinforces the scanned/not-scanned semantics of existingImports and the resulting currentUsage behavior.

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

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

The description states a specific verb and resource: classify runtime dependencies for conversion to direct UNPKG file lookups, with named output classifications and an import map. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as estimate_migration_impact or generate_importmap.

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 concrete pre-call guidance: read package.json yourself, pass only runtime dependencies, and scan HTML/files for existing import maps and CDN URLs before calling. It explains the consequence of not scanning, but it does not name alternative sibling tools or state when not to use this one.

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

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, open-world), so the description's job is to add context — and it does, disclosing that the file is actually verified to exist when a path is supplied. That tells an agent to expect a network round-trip and possible failure on a bad path, which the annotations alone would not reveal.

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?

A single tight sentence that front-loads the action and resource. It is information-dense without waste, though the parenthetical "(the original file lookup)" is slightly awkward phrasing rather than a clean differentiator.

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 five parameters, a policy enum, and an output schema, the description is adequate but thin: it does not state what the returned URL looks like in edge cases (unresolved version, missing entry point) or whether verification failure is an error or a warning. The presence of an output schema lowers the burden, so this is close to sufficient but not fully complete.

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

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

Schema coverage is 80%, so the schema already documents file, subpath, version, and the full policy enum with per-value meanings. The description adds only the framing "deliberate version policy" and does not explain precedence between file and subpath or how an unresolved version is handled, leaving it at 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 names a specific verb and resource ("Build a direct UNPKG file URL") and characterizes it as "the original file lookup", which hints at why it exists apart from siblings like resolve_package or verify_url. It stops short of explicitly naming an alternative tool, so an agent still has to infer the boundary.

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

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

Usage is only implied: the mention of a "deliberate version policy" and file verification suggests the tool is for constructing a pinned, known-good CDN link rather than listing or resolving packages. There is no explicit when-to-use or when-not-to-use statement and no sibling is named.

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 open-world, so safety is covered; the description adds the substantive behavior that the tool performs network resolution against UNPKG and that framework-managed packages are treated as errors when a framework is supplied or detected. This is real behavioral context beyond 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?

Two sentences, front-loaded with the purpose followed by workflow placement; the long check list is dense but each item is informative rather than padding. Minor cost is that the first sentence is quite packed, but nothing 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 an output schema present, return values need not be explained, and the description covers what is checked, when to invoke it, and the framework-dependent error rule. Only failure-handling and the severity/report shape beyond the schema remain unstated, which is a small gap for this complexity.

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

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

Schema coverage is only 50% and the framework enum has no per-value description, but the description explains that the framework parameter controls whether framework-managed packages become errors and that a framework may be auto-detected when not given. That adds meaning the schema does not convey.

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 and resource ("Validate an existing or proposed import map") and then enumerates the concrete checks performed: UNPKG URL resolution, file existence, version consistency including react/react-dom pairing, loose specs, and framework-managed packages. This clearly distinguishes it from siblings like audit_dependencies and generate_importmap.

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 sequencing: "Run this after generate_importmap or an audit, before committing to a conversion," which tells the agent where this fits in the workflow relative to named siblings. It stops short of stating conditions where validation should be skipped or what to do on failure, 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.

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

Annotations already carry readOnly/idempotent/non-destructive, so this description does not need to restate safety. It adds genuinely non-obvious behavior beyond them: results are range-based with explicit assumptions and caveats, and the tool deliberately excludes latency and Core Web Vitals forecasting. It does not describe how the dollar figure behaves when the cost parameter is omitted beyond the schema's brief note.

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 first, scope limits second, input sourcing third. Every sentence contributes, though the sourcing sentence is dense and packs multiple clauses that could be slightly cleaner. No filler or repetition.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on caveats and inputs instead. For a four-parameter read-only estimator the coverage is strong; the minor gap is that the effect of the default browser cache rate on results is not discussed.

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 75%, so the baseline is near 3, but the description adds real meaning: it explains that bandwidthCostPerGbUsd is optional and only enables the dollar calculation, and it supplies provenance for unpkgBytesPerPageLoad via audit_dependencies. Only monthlyPageViews remains entirely unexplained, and its meaning is self-evident.

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: an order-of-magnitude estimate of bandwidth offloaded and hosting dollars when bytes move from first-party hosting to UNPKG. It also distinguishes itself from the sibling audit_dependencies by naming that tool as the upstream source of one input, so an agent can tell the two apart 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?

It states the context in which the tool applies (bytes moving to UNPKG, optional $/GB to include dollars) and explicitly bounds when not to rely on it: it cannot forecast latency or Core Web Vitals. It also prescribes how to obtain the key input from audit_dependencies' impact.convertNowEntryBytes. What it lacks is a named alternative for scenarios where a range estimate is insufficient.

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 usefully adds that entry files are resolved live from each package (i.e., network lookups at call time), but says nothing about failure behavior for unknown packages or how unpinned versions resolve to a moving latest.

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 short sentences with the outcome front-loaded and no filler; the second sentence adds the live-resolution caveat. Nothing is redundant with the 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?

An output schema exists, so return format needn't be explained, and annotations cover safety and open-world access. What remains thin is the edge-case behavior (unknown packages, unspecified version resolution) for a tool that performs live network lookups.

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?

Top-level schema coverage is 0% for the single 'entries' parameter, so the description should compensate; it conveys the concept (a set of bare specifiers mapped to package URLs) and that entry points default unless a file is given, matching the nested 'file' default. It does not explain the optional version field or the per-entry package/specifier relationship in any detail.

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

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

States a specific verb and resource: resolve bare specifiers to UNPKG file URLs and return a ready-to-paste import map. This clearly distinguishes it from check_importmap or build_file_url by outcome (generated map vs. validation vs. single URL), though it never names those siblings.

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

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

Usage is only implied by the phrase 'ready-to-paste import map' — an agent can infer this is the creation step before check_importmap, but the description never says when to use this instead of resolve_package or check_importmap, nor any prerequisites.

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 open-world behavior, so the safety profile needs no restating. The description adds the underlying mechanism (UNPKG ?meta) and the important trait that results reflect real archive contents rather than inference, but says nothing about failure modes for unresolvable packages or truncation when limit is hit.

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 tight sentences with the action first and the usage constraint second; nothing is redundant and every clause carries 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 an output schema present and rich annotations, the description need not explain return values, and it covers scope, source, and usage. It is slightly thin on edge cases (nonexistent package, limit truncation) for a tool whose whole purpose is to be the authoritative path source.

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 75% and documents path, limit, and version defaults/resolution, so the schema carries most parameter meaning. The description only reinforces that the version may be 'exact or resolvable' and leaves the bare 'package' parameter to 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 ('List the real files inside ... a package version') plus the data source ('via UNPKG ?meta'), which is enough to tell it apart from URL-building or resolution siblings. It stops short of explicitly naming which sibling to use instead when you already know a path (e.g., build_file_url).

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

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

'Use this before choosing a file path; never guess paths' gives a clear activation condition and an explicit prohibition. It does not name alternative tools or state what to do when the package/version cannot be resolved, so the routing guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description still adds real value by clarifying that the lookup hits live npm state ('exists on npm today', implying results are not cached or stale) and that browser entry points come back. That is useful beyond the annotations, but there is no mention of error behavior for nonexistent packages or network/rate-limit considerations for an open-world call.

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

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

Two sentences with the core behavior first and the usage directive second. No redundant restatement of the title or name, and every clause adds 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 an output schema present, return values need not be enumerated, and the description still previews that browser entry points are included. Combined with annotations covering side-effect profile, this is nearly complete for a two-parameter read tool; only failure modes for unknown packages are 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%, and the description largely restates the schema's own wording (exact version, dist-tag, semver range). It does not explain precedence when both a range and a tag could apply, or how pre-release versions are treated. Baseline 3 is appropriate since the schema carries the 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?

States a specific verb and resource ('Resolve a package name plus exact version, dist-tag, or semver range') plus the scope of the answer ('the version that exists on npm today, with its browser entry points'). It never names a sibling, so an agent cannot tell from the text alone why this beats search_packages, but the purpose itself 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?

Gives explicit when-to-use guidance by naming the alternative behavior to avoid: 'Use this instead of recalling versions from memory.' That is a clear trigger condition. It stops short of saying when NOT to use it or pointing to search_packages for discovery, so it is strong but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), yet the description adds real behavioral value: ranking is npm relevance order and readiness is annotated rather than filtered, so CJS-only results remain visible. It stops short of mentioning rate limits, auth, or network failure 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?

Purpose is front-loaded in the first clause, and each subsequent phrase carries new information (readiness categories, entry file/size, ranking, non-filtering). The middle sentence is long and stacks several clauses, but nothing is redundant.

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, a complete input schema, and rich annotations, the description supplies what those cannot: what the readiness annotations mean and that results are not silently dropped. Only the relationship to sibling resolution tools 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 query and limit are already documented, including the default of 5 and the maximum of 10. The description's "search for a need" phrasing reinforces that query is intent-based rather than a package name, but adds no syntax 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 ("Search npm") plus a concrete example-driven notion of the input ("a need (e.g. 'date picker', 'markdown parser')"), and the added value (browser-readiness annotation for UNPKG lookup) distinguishes it from siblings like resolve_package or shield_check_packages.

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

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

Usage is implied: this is the discovery entry point that produces candidates annotated for direct UNPKG file lookup. However, it never explicitly says when to prefer this over resolve_package or shield_check_packages, nor does it describe prerequisites or follow-up steps, so the agent must infer the 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?

Goes well past the annotations by disclosing tiered auth limits (25 anonymous vs 200 authenticated) and, critically, the semantic caveat that missing pairs were not scanned yet so absence is not a clean verdict. That last point changes how an agent interprets a null result and is not derivable from readOnlyHint/idempotentHint.

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, front-loaded with the verdict/CVE outcome, then limits, then the caveat. No sentence is filler and nothing repeats the annotations or schema.

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

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

For a read-only single-parameter tool with no output schema, the description appropriately previews return contents (verdict, review state, CVEs, first patched version) and sets expectations for unscanned packages. The remaining gap is package identity format, which matters because the whole query hinges on exact name@version matching.

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

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

With 0% schema description coverage the description must compensate, and it partly does: it establishes that entries are exact name@version pairs and that the effective cap varies by auth tier (tighter than the schema's maxItems of 200). It never identifies the package ecosystem or accepted name format (scoped npm names, etc.), leaving the single parameter's vocabulary ambiguous.

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

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

States a specific verb and resource ('Check exact package@version pairs against Shield intel') and names the two return payloads: malware verdict with review state, and CVEs with first patched version. This is clearly distinguishable from siblings like shield_domain_packages (domain-level data) and shield_watchlist_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 concrete operating context: anonymous calls for packages you name are capped at 25, Shield login raises to 200, and domain data requires login (routing that need to the domain sibling). It does not explicitly say when to prefer search_packages or resolve_package first to obtain exact versions, so the when-not guidance is only partial.

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 openWorld, so the safety profile is covered. The description adds genuine context beyond that: it requires a Shield login, threat-mode results are annotated with malware verdicts and CVEs, and results are ranked by the domain's own traffic.

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 tight sentences with the primary listing behavior front-loaded, followed by the threats-mode qualifier and the login requirement. Every clause carries information and there is no redundant restatement 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?

For a three-parameter, no-output-schema read tool, the description covers both modes, the auth prerequisite and the threats-mode enrichment. Minor gaps remain around the return shape and whether days has any effect outside threats mode, which keeps it from a 5.

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 already documents all three parameters, including the days default and 0 = all-time. The description reinforces the domain/includeThreats coupling and adds the ordering behavior, but adds little new parameter meaning.

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 and clearly separates the tool's two modes: listing the caller's verified domains with package counts, or listing Shield-observed packages for one domain. It does not explicitly differentiate itself from the sibling shield_check_packages, so it falls just short of a 5.

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

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

It states the selection rule for its own modes plainly: 'Omit [domain] to list domains with package counts' and 'With includeThreats, one domain's packages come back annotated...'. That is clear conditional guidance, but it gives no when-to-use/when-not guidance relative to sibling tools such as shield_check_packages or shield_watchlist_status.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it operates under the logged-in user's effective rules (an auth/identity dependency) and uses 'the same rule-matching semantics as the edge' (a fidelity guarantee), which tells the agent results are authoritative previews rather than approximations.

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?

A single front-loaded sentence with no filler; the simulated object, the rule source, and the fidelity claim all appear before any optional detail. Slightly dense but every clause carries 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 no output schema, the description should describe what the preview returns (a verdict? matched rule? block reason?), which it only gestures at with 'what Shield would do'. Combined with an unexplained 'path' parameter, the definition is adequate but leaves real gaps for a simulation tool whose output shape is its whole point.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that package and version form a single package@version request and that referer/origin are optional contextual inputs, but the fifth parameter 'path' is never mentioned and no format examples are given for origin or referer.

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 ('Preview what Shield would do for one package@version request') and scopes it to the logged-in user's effective pin/block rules. It does not explicitly contrast itself with the sibling shield_check_packages, so an agent must infer that this is the single-request simulation versus the batch check, but the core 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?

The word 'Preview' and 'Simulate' imply a safe dry-run use case, and the parenthetical '(optionally with referer/origin)' signals when the extra contextual parameters matter. However, there is no explicit when-to-use/when-not guidance and no named alternative sibling, leaving the agent to reason about choosing this over shield_check_packages.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value beyond them by stating the auth prerequisite ('Requires Shield login') and that results reflect what Shield 'currently holds', signaling live authoritative state rather than a cached or computed view.

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

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

Two sentences, front-loaded with what is returned and followed by the single prerequisite. No redundant restatement of the title or name and nothing that could be trimmed.

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

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

For a zero-parameter, read-only tool with no output schema, the description covers the essentials: what data comes back (three named categories) and the login requirement. It does not describe the response shape or whether entries include metadata such as versions or timestamps, which would be the last useful addition given the absent output schema.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level meaning is missing.

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 ('Return') and three concrete resource categories: monitored packages, blocklist entries, and pin policies, scoped to the logged-in org. This clearly separates it from shield_check_packages (which evaluates packages) and shield_whoami (identity), though it does not name those siblings 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?

Usage is implied rather than stated: an agent can infer this is the tool for reading current Shield watchlist state, and the prerequisite 'Requires Shield login' is given. There is no explicit guidance on when to prefer this over shield_check_packages or shield_domain_packages, so the agent must infer the boundary.

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 open-world, so the safety profile is covered. The description adds genuinely new behavior: a prerequisite of an approved Shield account and the concrete error contract (authorization_required with reconnect instructions) for anonymous connections, which an agent needs to handle failure 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?

Two sentences, no filler, with the return payload front-loaded and the authorization caveat second. Every clause carries information an agent would otherwise have to discover by trial.

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

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

For a zero-parameter, read-only identity lookup with no output schema, the description covers what is returned at a coarse level, the eligibility prerequisite, and the error path. Since no output schema exists, the exact shape of the account/entitlements payload is left unspecified, which is the only remaining gap.

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 takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly adds no redundant parameter discussion.

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

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

The description uses a specific verb and resource: it returns the Shield account, organization, and entitlements, scoped to the OAuth login on this connection. That scope detail separates it from list/check-style siblings such as shield_check_packages or shield_watchlist_status, though it never names an alternative tool 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?

Usage is implied rather than stated: an agent can infer it should call this to discover identity/entitlements for the current connection, and it learns the precondition (approved Shield account) plus the failure mode for anonymous connections. There is no explicit when-not-to-use guidance or named alternative among the sibling tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds a genuine behavioral detail beyond them: it follows redirects, which tells the agent that a bare 3xx is not a failure and that a network round-trip occurs. It does not say what a failed resolution returns, but the output schema covers return values.

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?

One short sentence that front-loads the action and constraint with zero filler. Nothing in it is redundant with the title or schema.

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

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

With rich annotations, an output schema, and fully documented parameters, the description only needs to convey purpose and timing, and it does. The minor gap is not stating how an unresolvable URL is surfaced versus thrown, though the output schema likely handles 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?

There is a single parameter with 100% schema description coverage, so the schema already specifies that a full https://unpkg.com/... file URL is required. The description only implies the same constraint and adds no format, encoding, or scoping detail beyond it.

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

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

States a specific verb and resource ('Check that a UNPKG file URL actually resolves'), which distinguishes it from siblings like build_file_url or resolve_package that construct or inspect rather than verify liveness. It does not name any sibling explicitly, so differentiation is inferred rather than stated.

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?

'before you put it in a project' gives a clear timing cue for when to reach for this tool, which is more than a bare purpose statement. It stops short of explicit exclusions or naming the alternative (e.g., build_file_url for constructing the URL first), so an agent must infer that this is a post-construction check.

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