bouncer_check_manifest

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

Annotations already declare readOnlyHint and openWorldHint, so safety and network access are covered. The description adds non-obvious execution behavior: it runs as an MCP Task with live progress and orders results BLOCK/REVIEW first with a reason and safe version. It stops short of describing rate limits, registry auth, or what a fully clean result looks like.

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 compact sentences, purpose and scope first, then execution/return characteristics. No filler, and the distinctive detail (newest match for range today) is front-loaded.

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

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

For a two-parameter, no-output-schema tool, the description covers purpose, trigger scenario, async task mode, and result ordering. It leaves the shape of a non-BLOCK/REVIEW result and any polling/lifecycle expectations for the task mode unstated, but nothing critical to invoking 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% (both parameters fully described, including includeDev), so the baseline is 3. The description goes slightly beyond the schema by explaining the version-resolution semantics applied to packageJson ('the newest match for its range today'), which is the behaviorally important part of the input.

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 every dependency in a package.json') and pins down the version resolution rule ('the version npm would install for its range today (the newest match)'), which separates it semantically from a single-package check. It never names a sibling like bouncer_check_package explicitly, so the differentiation is inferable 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?

Provides a concrete triggering scenario: 'before running `npm install` in a cloned repo'. That gives clear context for when to reach for this tool, but there are no explicit exclusions and no routing guidance against the six sibling tools (e.g. check_upgrade or check_package).

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