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

The annotations only declare readOnlyHint and openWorldHint. The description adds context beyond them: this is not a live test, the record may be days old, a missing record returns seen=false with known=false and is not proof the port is closed, and each successful call costs $0.002 in USDC via x402, while failed calls are free. Together these cover staleness, false-negative interpretation, and cost, which are the behaviors an agent needs before spending money on a 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?

The core purpose and the interpretation caveat are front-loaded in the first two sentences, and the pricing note earns its place because it affects whether an agent should call the tool. The sibling sentence is the weak point: the 'Related tools on this server, for a different need' framing is wordy and its second clause is truncated into an ungrammatical fragment.

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 one-parameter, read-only lookup, this description is complete. An output schema exists, so return values do not need to be documented, but the description still explains how to read the seen/known fields. Combined with the cost and staleness notes, an agent has everything needed to decide, call, and interpret the result.

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 required parameter, and the schema describes it at 100% coverage ('IPv4 address such as 1.1.1.1'), so the schema already does the work. The description restates that the input is an IPv4 address but adds no syntax, validation, or formatting detail beyond it, which is the baseline expectation when coverage is complete.

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: it reads Shodan's passive scan records for TCP port 3389 on an IPv4 address. It also names the sibling tools that cover ports 445 and SNMP, so an agent can separate this tool from security_smb_exposure_test, security_snmp_exposure, and security_shodan_host_summary without opening a schema.

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 explicitly routes the agent to security_smb_exposure_test for port 445 and security_snmp_exposure for SNMP, and it names the context: checking Shodan's pre-collected data rather than a live scan. However, the sentence describing security_snmp_exposure is garbled and incomplete ('when you need reports whether Shodan's pre-collected passive scan data'), and it never points to security_open_port_scanner for a live probe, which is the most important alternative to rule out.

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