search_ip2location

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

With no annotations provided, the description carries full burden. It discloses that the tool is passive and uses public-source collection, and lists the types of data returned. It does not cover rate limits or error handling, but the key behavioral traits (read-only, API key needed) are clear.

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?

Five focused sentences with no redundancy. Each sentence adds distinct value: enhanced capability, output details, sponsorship, prerequisite, usage restriction, and passive nature. Front-loaded with purpose.

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 tool with no output schema, the description adequately describes return values (geolocation, ISP, ASN, detections). It also covers authorization and API key requirements. It is slightly lacking in error handling details (e.g., invalid IP, missing API key), but overall complete for the scope of this tool.

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 50% (json_output described in schema). The description does not add parameter-specific details beyond the schema's description of json_output. For the 'ip' parameter, the description implies it is an IP address but provides no format or constraints. Baseline 3 is appropriate as description adds minimal value over schema.

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 it provides 'Enhanced IP intelligence' including geolocation, ISP, ASN, and detection of VPN, proxy, Tor, and datacenter hosting. This distinguishes it from simpler sibling tools like search_ip by specifying the additional detection capabilities.

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 explicitly mentions the requirement for IP2LOCATION_API_KEY and authorized use only for own assets or authorized targets. It implies use when enhanced intelligence (VPN/proxy detection) is needed, but does not directly contrast with alternative sibling tools like search_greynoise or search_abuseipdb.

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