vdb_check_packages

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

No annotations are provided, so the description carries the full burden. It discloses the behavioral contract: each result carries an agent_action (REFUSE/CONFIRM/PROCEED), a top-level agent_action exists, and the agent must follow them and relay 'because' on refusal. It also explains that the call acts as a typo test. However, it doesn't explicitly state whether the operation is read-only or has side effects, though 'check' implies non-destructive. Slight gap, but the disclosed behavior is rich enough to guide correct invocation.

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

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

Three sentences, no waste. The purpose and preference are front-loaded, followed by essential behavioral and parameter guidance. Every sentence earns its place; the description is both concise and information-dense.

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 bulk-check tool with no output schema, the description provides sufficient context: it describes the result structure (per-item and batch agent_action), instructs on how to handle results (follow them, relay 'because'), and explains the typo-test nature. An agent has enough information to call this tool correctly and interpret responses, despite not knowing the exact JSON field names.

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 parameter type and description are already present. The description adds critical semantic guidance: 'Send names EXACTLY as written — do not correct a typo first, the call is the typo test.' This is beyond the schema and is essential for correct usage, elevating the parameter understanding beyond a simple list.

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

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

The description clearly states the tool's purpose: bulk-checking multiple packages in one call, and explicitly differentiates it from the sibling vdb_check_package by recommending this over repeated calls. The verb 'bulk-check' and resource 'packages' are specific and 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?

It gives an explicit directive to prefer this tool over vdb_check_package, which is a clear usage guideline. It also instructs the agent to send names exactly as written and not to correct typos, framing the call itself as the typo test. This provides both when-to-use and how-to-behave guidance.

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