Forbidden Candidates

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

The description states 'Read-only.' and mentions 'one cheap HEAD per URL' which goes beyond the annotations (readOnlyHint: true, destructiveHint: false). It describes the network behavior (HEAD requests) and the filtering outcome (returns 403s), providing transparency about side effects. Minor gap: does not discuss error handling or rate limits, but sufficient for the tool's simplicity.

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 concise (two sentences) and front-loads the core purpose. It efficiently includes relevant sibling-tool references and the HEAD request detail without unnecessary wording. The structure is clear and focused.

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?

The description provides the essential context for a simple tool: what it does, how it fits with other tools, and the general output ('returns the 403s'). However, it lacks explicit details about the output structure (e.g., just a list of URLs, or with status codes) and does not mention edge cases or performance implications. Given the tool's simplicity and single parameter, this is adequate but not exhaustive.

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 input schema has zero description coverage for the 'urls' parameter. The description only says 'Give it URLs from http_probe or content discovery' which gives source context but does not specify URL format (e.g., absolute vs relative, scheme requirements), constraints, or examples. With 0% schema coverage, the description must compensate more thoroughly, but it does not.

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: 'Pre-check a list of URLs and return the ones that actually return 403.' It explicitly differentiates from sibling tools by mentioning that 'forbidden_bypass refuses anything that is not 403' and positioning this tool as the pre-filter, making its role distinct in the workflow.

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 provides explicit usage guidance: 'Give it URLs from http_probe or content discovery that looked interesting; it tells you which are worth the bypass pass.' It also clarifies the tool's relationship to forbidden_bypass and notes it uses 'one cheap HEAD per URL', indicating when and how to use it.

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