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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses significant behavioral details: monetary cost per call ($2) and the statistically noisy nature of reputation hits for benign infrastructure. These are meaningful operational traits not captured by annotations, though it does not cover response format 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?

Three sentences, front-loaded with the core purpose. Each sentence provides distinct value: what it does, cost/positioning, and a crucial caveat. No redundant phrasing.

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 explains purpose, cost, and interpretation caveats, which are essential. However, with no output schema, it omits what the response structure looks like (e.g., source-specific verdicts, scores, timestamps), which an agent may need to interpret or act on results. It also misses the fact that more indicator types than IP/domain are accepted.

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 schema has 3 parameters with only 33% description coverage (only previous_scan_id gets a description). The tool description says 'for an IP or domain', but the indicator_type enum includes url and hashes, so it under-specifies accepted types and could mislead the agent into thinking only IP/domain are supported. It also does not explain the previous_scan_id parameter at all.

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 uses a specific verb+resource structure: 'Reputation and indicator lookup for an IP or domain across AbuseIPDB, AlienVault OTX and abuse.ch.' It clearly distinguishes from siblings like cve_lookup or dns_security_check by focusing on threat reputation across named sources. The phrase 'cheapest way to check whether an indicator is known-bad' further clarifies its role.

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 gives a clear usage context ('cheapest way to check whether an indicator is known-bad') and includes important cautions about interpreting results (CDN/cloud/payment infrastructure false positives). However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusion criteria.

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