shodan-honeypot-score

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

With no annotations, the description carries the full burden. It discloses a prerequisite ('Requires a Shodan API key'), explains the output scale (0.0 to 1.0), and mentions the return type ('HoneypotResult'). This adds useful context beyond the tool name and schema, though it doesn't cover error cases or rate limits.

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 moderately concise but contains redundancy: the second sentence ('Returns a probability score...') and the final 'Returns:' section repeat the same information. The structure is logical but could be trimmed to a single return-statement without losing meaning.

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 covers the tool's purpose, the meaning of the score range, a practical use case, the API key prerequisite, and the return type. For a simple single-IP lookup tool with a well-covered schema and output schema, this is complete enough. It lacks only minor details like error handling behavior.

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 already has 100% coverage: ip is described as 'IP address to check' and timeout as 'HTTP request timeout in seconds.' The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 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 opens with a specific verb and resource: 'Check if an IP address is likely a honeypot.' It clearly differentiates from all sibling tools by focusing on honeypot detection, which no other Shodan tool in the list covers. The scope (single IP) is explicit.

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 states a clear use case: 'Useful for filtering scan results and identifying deceptive hosts.' This provides contextual when-to-use guidance without explicit exclusions. It doesn't name alternative tools, but the uniqueness of the honeypot feature makes the intended usage obvious.

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