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

With no annotations, the description carries the full burden. It discloses the authentication requirement and lists the returned fields, but does not mention potential failure modes, rate limits, or other behavioral aspects. It is adequate for a simple read-only profile endpoint but not rich.

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 short and front-loaded with the primary purpose. It includes a brief list of return fields and a note about the API key. The final 'Returns' line is slightly redundant with the previous sentence, but overall it is concise and well-structured.

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?

Given the tool's low complexity, an output schema that likely covers return values, and full parameter documentation in the schema, the description provides sufficient context: purpose, key fields, and authentication requirement. It is complete enough for an agent to use it correctly.

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 description coverage is 100% — the only parameter 'timeout' is fully described in the schema. The description does not add any extra meaning to the parameter, so baseline 3 is appropriate.

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 with a specific verb ('Get') and resource ('your Shodan account profile information'). It is distinct from most siblings, but does not explicitly differentiate from the similar 'shodan-api-info' tool, which might also relate to account or API details.

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 a prerequisite (API key) but does not explain when to use this tool versus alternatives. There is no explicit when-to-use or when-not-to-use guidance, and the presence of 'shodan-api-info' as a sibling creates potential ambiguity that is not addressed.

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

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

With no annotations provided, the description carries the full burden. It discloses the requirement for a Shodan API key and indicates a return type, which is important context. As a simple read-only info check, this is adequate transparency.

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 and front-loaded with the core purpose. It uses a clean structure with a Returns section, and every sentence contributes value without waste.

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 tool is simple with one optional parameter and an output schema. The description covers purpose, usage context, and expected result, making it complete for an agent to select and invoke the tool correctly.

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 only parameter (timeout) is fully described in the schema with default, range, and type. The description adds no additional parameter semantics. With 100% schema coverage, the baseline score of 3 is appropriate.

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 checks Shodan API key usage, including plan type, remaining credits, and limits. This specific verb+resource combination distinguishes it from sibling tools that handle IP lookups or searches.

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 clear context by stating it is useful for monitoring API usage and checking remaining query/scan credits. It does not explicitly mention alternatives or when not to use, but the distinct purpose makes the usage scenario clear.

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

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

With no annotations provided, the description carries the full burden. It discloses that the endpoint is free and does not require a paid API key, which is relevant behavioral info. It also lists the types of data returned. However, it does not mention rate limits, error handling, or any side effects, though for a read-only lookup this is less critical.

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, approximately three sentences, and front-loads the purpose. The 'Returns: CveResult...' line is somewhat redundant given the output schema and the earlier mention of return fields, but the overall structure is efficient and readable.

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 simple lookup tool with an output schema and well-documented parameters, the description is adequately complete. It states the function, output contents, and cost/auth status. Missing details like rate limits are not critical for this tool, but their absence prevents a perfect score.

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 100%, so the baseline is 3. The description does not explain parameters beyond the schema, but the schema already documents cve_id with an example and timeout with default and max. The description adds value by stating what the returned data contains, but not parameter-specific semantics beyond the 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 the tool's verb and resource: 'Look up CVE details from Shodan's vulnerability database.' It distinguishes itself from siblings like shodan-search-cves (which searches CVEs) by focusing on lookup of a specific CVE ID. The return fields (CVSS, EPSS, references, CPEs) further specify the purpose.

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 implies usage when you have a specific CVE identifier to look up, especially since the schema requires 'cve_id'. However, it does not explicitly mention when to avoid this tool or name alternatives from the sibling list. The note that it's free and does not require an API key is a useful context but not a direct usage guideline.

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

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

No annotations are provided, so the description carries the full burden. It adds the prerequisite of a Shodan API key and states the return type (DnsResolveResult). However, it does not disclose whether the operation is read-only, any rate limits, error behavior, or whether it consumes API quota. For a simple DNS lookup, some of this may be implicit, but the description lacks thorough behavioral context.

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, with four short sentences that front-load the purpose. Every sentence earns its place: purpose, use case, prerequisite, and return type. No redundancy or fluff.

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?

Given the tool's simplicity, the presence of an output schema, and full parameter descriptions, the description is largely complete. It adds the API key requirement and a workflow suggestion. It lacks edge-case behaviors like error handling or rate limits, but these are not critical for a basic DNS resolution 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?

The input schema has 100% coverage with descriptions for both 'hostnames' and 'timeout'. The tool description does not add any parameter-specific details beyond what the schema already provides, so it meets the baseline for high schema coverage. No additional meaning is supplied.

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 clear, specific verb and resource: 'Resolve hostnames to IP addresses using Shodan's DNS service.' This immediately distinguishes the tool from the sibling shodan-dns-reverse (which resolves IPs to hostnames) and other lookups. The additional context about mapping domain names before IP lookups reinforces its purpose.

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 a clear usage context: 'Useful for mapping domain names to IPs before performing IP lookups.' This tells the agent when to use it, but it does not explicitly mention when not to use it or name alternative tools. No exclusions, but the context is clear enough.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does mention the API key requirement and the return type, which are useful. However, it does not explicitly state that this is a read-only operation, nor does it mention rate limits, error conditions, or side effects. The safety profile is implied but not stated.

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 compact and front-loaded: the first sentence states the core purpose, followed by a single use-case sentence, a prerequisite, and a returns line. No filler or redundant content; every line earns its place.

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?

Given the simple tool and full schema coverage, the description is almost complete. It covers purpose, use case, API key requirement, and return type. The output schema already documents the result structure, so the 'Returns' line is a helpful confirmation rather than a necessity. Missing details like rate limits or error handling are minor for a DNS lookup 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 100%, so the baseline is 3. The description adds no extra parameter-level context beyond the schema. The schema already explains the 'ips' format (comma-separated, maximum 100) and the 'timeout' default/maximum. The description's mention of 'IP-to-hostnames mappings' is a high-level outcome rather than parameter semantics.

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 'Reverse DNS lookup — find hostnames for IP addresses', a specific verb+resource statement that clearly defines the tool's function. It also distinguishes itself from the sibling 'shodan-dns-resolve' (likely forward DNS) by explicitly saying 'reverse' and explaining the IP-to-hostname direction.

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 a clear use case: 'Useful for identifying what domains are hosted on specific IPs.' This tells the agent when to apply the tool, though it does not explicitly name alternative tools or state when not to use it. The reverse DNS framing implicitly contrasts with forward DNS siblings.

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

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

With no annotations, the description discloses the API key requirement and the return object, adding context beyond the schema. It does not cover rate limits or explicitly confirm read-only behavior, but for a simple DNS lookup the disclosure is reasonable.

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 tight and well-structured: a lead sentence, a value proposition, auth note, and a return summary. Every sentence earns its place with no fluff.

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 simple two-parameter domain lookup, the description covers purpose, use case, authentication, and return type. The output schema further covers return structure, making the description sufficiently complete.

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 description coverage is 100%, with both 'domain' and 'timeout' well-documented in the schema. The tool description adds no extra parameter semantics, so the baseline 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?

Description clearly states the tool gets DNS information about a domain including subdomains, DNS records, and tags. It explicitly mentions domain reconnaissance and subdomain discovery, which distinguishes it from sibling DNS resolve/reverse and IP lookup tools.

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?

Provides a clear use case ('domain reconnaissance and subdomain discovery') but does not explicitly mention when not to use it or compare it to alternative tools. This is a clear context but lacks exclusions.

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

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.

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

With no annotations, the description carries the full burden. It discloses the read-only nature ('Show'), the auth requirement, and the return type (HttpHeadersResult). It does not mention rate limits or failure modes, but for a simple introspection endpoint this is acceptable.

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 brief and front-loaded, with each sentence contributing useful information. The 'Returns:' block is clear and avoids redundancy.

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?

Given the tool's low complexity (one optional parameter, simple output) and the presence of an output schema, the description covers the essential context: purpose, auth, use case, and return format. No significant gaps remain.

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 single parameter (timeout) has a complete schema description covering semantics, so the description adds no additional value. Baseline 3 is appropriate since schema coverage is 100%.

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 shows HTTP headers sent by the client, using a specific verb ('Show') and resource. The first sentence unambiguously distinguishes this from sibling tools like IP lookup or search.

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 clear context ('Useful for debugging') and a key prerequisite ('Requires a Shodan API key'). It does not explicitly mention alternatives, but the tool's niche is self-evident given the sibling list, so this is a minor gap.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly describes what the tool returns, that it's free, and that it's faster but less detailed than the alternative. While it does not discuss error handling, rate limits, or explicit read-only nature, it provides substantial transparency for a simple lookup operation.

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 and front-loaded, with the key purpose in the first sentence. However, the final 'Returns: InternetDbResult with quick IP intelligence data' is somewhat redundant with the earlier 'Returns open ports...' sentence. It is still efficient overall, but could be tightened by removing repetition.

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 simple two-parameter lookup tool with an output schema, the description is complete. It covers purpose, return data, cost (free), speed tradeoff, alternative tool, and output type. The output schema handles return structure, so no additional explanation is needed. The description is fully adequate for an agent to select and invoke the 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 description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific details beyond the schema; it only mentions the output data. The schema already fully documents 'ip' and 'timeout', so the description adds no additional semantic value for parameters.

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 performs a quick IP intelligence lookup returning open ports, vulnerabilities, hostnames, CPEs, and tags. It also distinguishes itself from the sibling 'shodan-ip-lookup' by noting it's faster but less detailed. The verb 'Returns' and resource 'Shodan's InternetDB' make the purpose 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 explicitly names an alternative tool ('shodan-ip-lookup') and provides a comparison ('Faster but less detailed'), giving clear guidance on when to use this tool versus the alternative. It also states it's free and requires no API key, which helps the agent decide based on constraints.

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

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

With no annotations, the description discloses key behavioral traits: passive (no packets sent), returns a structured host result, and includes an authorization warning. However, it doesn't address potential API key requirements or rate limits, a minor gap.

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?

Four sentences front-loaded with purpose, followed by a compact list of returned data and a behavioral note. No redundant phrases except slight repetition of 'Shodan.' Efficient.

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 2-param tool with output schema and full schema param descriptions, this description is sufficiently complete. It covers what data is returned, passive behavior, and authorization. Missing rate-limit/API-key nuances but not critical.

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 covers both params (target and timeout) with 100% coverage. Description doesn't add detail beyond the schema, but none is needed given the schema's clarity. Baseline 3.

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?

Clearly states the tool looks up IP info via Shodan, listing specific data types (ports, services, banners, etc.). However, it doesn't explicitly differentiate from sibling tools like shodan-internetdb-lookup, so it misses a chance to guide selection.

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?

Provides context that this is passive reconnaissance and only for authorized targets, which implies when to use (assessment). But doesn't name alternatives or exclusions, so it's clear context without explicit alternatives.

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

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

The description discloses the API key requirement and the return type (SearchFacetsResult), but doesn't elaborate on error handling, rate limits, or side effects—though none are apparent for a read-only list operation. With no annotations, there is some burden to explain behavior, but the simplicity of the operation keeps the score at a moderate level.

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 and well-structured: a clear one-line purpose, usage context, a requirement, and a return type. Every sentence earns its place with no fluff or redundancy.

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 one optional parameter, an output schema, and low complexity, the description provides sufficient context: it names the tool's purpose, how it fits with sibling tools, the API key prerequisite, and the return type. It is complete for the tool's simplicity.

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 100% description coverage for the single optional parameter (timeout), including its default and range. The tool description adds no extra parameter semantics, so the baseline 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 clearly states the tool's function: 'List available search facets for Shodan queries.' It uses a specific verb and resource, and distinguishes itself from sibling tools like shodan-list-filters and shodan-list-ports by focusing on facets with concrete examples (country, org, port).

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 suggests using facets with shodan-search-count for result distribution analysis, providing a clear context for use. It also notes the API key requirement, which is a useful prerequisite. It doesn't mention alternatives or exclusions, but the guidance is sufficient for a simple list tool.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the API key requirement and indicates the return type (SearchFiltersResult). However, it offers no detail about error behavior, rate limits, or data freshness. For a simple read-only list operation, this is adequate but not rich.

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 compact and well-organized: a clear one-line purpose, a brief explanatory sentence with examples, a usage hint, a prerequisite note, and a structured 'Returns:' section. Every sentence earns its place with no redundancy.

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 one optional parameter and an output schema, the description is complete. It states what the tool returns, the prerequisite (API key), and the purpose. The presence of an output schema means the description doesn't need to detail return fields, and it doesn't over-explain.

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 100% coverage for the single 'timeout' parameter, so the description does not need to repeat it. The description provides no additional semantic meaning beyond the schema, but the baseline of 3 is appropriate given full schema coverage.

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: 'List available search filters for Shodan queries.' It provides concrete examples (port:, country:, org:, product:) and explicitly ties it to shodan-search, distinguishing it from sibling tools that list facets, ports, or protocols.

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 says 'Use these to discover all available filter options for shodan-search,' which gives clear context for when to use this tool. It also notes the API key requirement as a prerequisite. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions the API key requirement and the return type ('PortsResult with list of scanned port numbers'), but it does not disclose potential errors, rate limits, or any other behavioral traits. This is adequate for a simple read-only list operation but lacks rich context.

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 appropriately short and front-loaded with the primary action. However, it contains slight redundancy—'List port numbers that Shodan crawlers are actively scanning' and 'Returns the list of ports that the Shodan crawlers are looking for on the Internet' convey similar information. Still, it is overall efficient and well-structured.

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?

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description is relatively complete. It covers the purpose, the API key requirement, and the return type. It does not explain error handling or further details, but for a straightforward list operation, it provides sufficient context.

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 only parameter, 'timeout', is fully described in the input schema (100% coverage per context signals). The description adds no additional meaning to the parameter, so it falls at the baseline of 3 for high schema coverage.

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 function: 'List port numbers that Shodan crawlers are actively scanning.' The verb 'List' plus the specific resource 'port numbers' and the scope 'actively scanning' make the purpose unambiguous. It also distinguishes itself from sibling tools that list other entities like facets, filters, or protocols.

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 a clear context for use: 'Useful for understanding Shodan's scanning coverage.' It also notes a prerequisite ('Requires a Shodan API key'). However, it does not explicitly compare against alternative tools or state when not to use it, so it falls short of the highest bar.

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

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

No annotations are provided, so the description carries the burden. It discloses that an API key is required and describes the return value ('ProtocolsResult with protocol names and descriptions'). This is important behavioral context beyond the schema, though it does not discuss potential errors 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 extremely concise and front-loaded: the first sentence states the core purpose, a second sentence elaborates on the return value, and a third notes the API key requirement. Every sentence earns its place, with no filler.

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?

This is a simple list tool with a rich output schema and a fully documented input schema. The description adds the key prerequisite (API key) and specifies the return type, making it complete enough for an agent to select and invoke correctly without additional context.

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 100% coverage for the single `timeout` parameter, including its default and constraints. The description adds no extra parameter context, 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 starts with a specific verb+resource: 'List protocols available for on-demand Shodan scanning.' It clearly identifies what the tool does and distinguishes it from sibling list tools like shodan-list-ports and shodan-list-facets by focusing on protocols for on-demand scanning.

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 clear context for use ('protocols that can be used when launching an on-demand scan') and states a prerequisite ('Requires a Shodan API key'). It does not explicitly mention alternatives or when not to use, but the context is unambiguous for a listing tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the authentication requirement (Shodan API key) and the return format (string). It does not discuss potential errors or side effects, but for a simple read-only IP retrieval, this is adequate and adds value beyond the tool's name.

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 extremely concise and well-structured: a one-line purpose, a one-line use case, a one-line requirement, and a clear return type. Every sentence serves a purpose and there is no redundancy or filler.

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?

Given the tool's simplicity (one optional parameter, no required fields, and an output schema), the description covers all essential aspects: what it does, when to use it, what it requires, and what it returns. It is complete for an agent to select and invoke the tool correctly.

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 description coverage is 100% as the timeout parameter is fully described in the input schema. The description adds no additional parameter information, so it does not exceed the baseline for well-documented schemas.

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 function with a specific verb ('Get') and resource ('your current external IP address as seen by Shodan'). While it doesn't explicitly contrast with sibling tools, the name and description make it distinct from IP lookup or search tools, so it is clear but lacks explicit sibling differentiation.

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 a concrete use case ('checking what IP address your requests are coming from') and notes the requirement for an API key. It doesn't offer explicit alternatives or exclusions, but the context is sufficiently clear for when to use this tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the API key requirement and mentions the return type (QueryTokensResult), but does not discuss rate limits, error behavior, or the fact that the operation is non-mutating. This is moderate disclosure but incomplete.

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 compact and front-loaded with the primary purpose. The 'Returns' line is clearly separated for readability. Every sentence adds value, with no redundant or wasted text.

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?

With an output schema present and only two simple parameters, the description adequately covers the tool's function and return type. It provides enough context for an agent to select and invoke it correctly, though it could be more explicit about how it differs from sibling search tools.

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 provides 100% coverage for both parameters: query has a description and example, timeout has a description and default. The description adds no additional parameter semantics beyond what the schema already documents, 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 clearly states the tool's function with a specific verb and resource: 'Parse and analyze a Shodan search query into its components.' It further enumerates component types (attributes, filters, errors, search string), making the purpose explicit and distinct from siblings like shodan-search or shodan-search-count.

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 it is 'useful for debugging complex queries and understanding how Shodan interprets them,' providing clear context on when to use it. It does not explicitly mention alternatives or exclude other tools, but the context implies it is not for executing searches, and the API key requirement is noted.

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

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

With no annotations, the description carries the full transparency burden. It discloses the need for a paid API key, issues an authorization warning, and states the return type (ShodanSearchResult). It does not explicitly mention read-only status, rate limits, or error handling, but the search verb and context make read-only behavior evident. This is above-average for a search tool.

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 and well-structured: a clear first line, a brief elaboration on capabilities, a requirements note, and a returns summary. Every sentence contributes useful information without redundancy. The IMPORTANT authorization note is appropriately emphasized.

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 combination of description, schema, and output schema covers the tool's operation well. It includes purpose, query syntax, auth requirements, and return type. Gaps include lack of explicit guidance on when to prefer sibling tools (e.g., shodan-search-count) and potential rate-limit behavior, but these are not critical given the schema and output schema.

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 description coverage is 100%, so the baseline is 3. The description adds value by listing filter categories (port, country, organization, product, version, and more) that go beyond the schema's examples. This helps the agent construct more effective queries without needing to infer filters from examples.

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: 'Search Shodan's database for hosts matching a query.' This clearly distinguishes it from sibling tools like shodan-search-cves (CVE search) and shodan-search-count (count only). It also names supported filters, reinforcing the purpose.

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 establishes a clear use case: finding internet-connected devices and services with Shodan's search syntax. It provides context on filters and requires a paid API key. However, it does not explicitly mention when to use alternatives such as shodan-search-count or shodan-ip-lookup, which would strengthen the guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses the key behavioral trait (does NOT consume query credits), the requirement for an API key, and the return type. It does not mention rate limits or error conditions, but the most critical behavioral differentiator is clearly stated.

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 short and front-loaded, with a clear structure: purpose, usage, requirement, and return value. However, 'does NOT consume query credits' is repeated twice, adding minor redundancy without contributing new information.

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?

Given the low tool complexity, an output schema, and full parameter documentation, the description covers all essential context: what the tool does, when to use it, the API key requirement, the credit behavior, and the return type. It is complete enough for an agent to invoke it correctly.

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 description coverage is 100%, with both 'query' and 'timeout' well-described including syntax examples and defaults. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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: 'Count how many hosts match a Shodan query'. It clearly distinguishes itself from sibling tools like shodan-search by highlighting that it does NOT consume query credits, making the tool's purpose unmistakable.

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?

Explicitly states when to use it: 'Use this to check result volume before running a full search.' This provides a direct use case and contrasts with the full-search alternative, giving the agent clear decision guidance. The schema further reinforces that the query syntax matches shodan-search.

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

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

With no annotations, the description discloses that the tool is free and requires no API key, which is a behavioral trait. It also indicates the return type (CpeSearchResult). However, it doesn't mention rate limits, data freshness, or any caveats about matching behavior. The non-destructive nature is implied by 'Search' but not explicitly stated. This is adequate but not rich.

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 brief, front-loaded with the primary purpose, and every sentence earns its place: purpose, use case, free/no-key note, and return type. There's no redundancy or filler.

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 tool is relatively simple with 4 parameters, all covered by the schema, and an output schema explaining the return structure. The description adds context (free, use case) and is complete enough for an agent to decide to invoke. It doesn't need to explain return values because the output schema exists.

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 description coverage is 100%, so the schema already documents all parameters with descriptions and examples. The description's phrase 'by product name' aligns with the 'product' parameter but adds no new semantic detail beyond the schema. According to the rubric, high schema coverage warrants a baseline of 3, and the description doesn't exceed that baseline.

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 function: 'Search CPE (Common Platform Enumeration) identifiers by product name.' It specifies the resource (CPE identifiers) and the filter (product name), and distinguishes itself from sibling tools by noting it's for finding exact CPE strings for vulnerability lookups.

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 clear usage context: 'Useful for finding exact CPE strings to use in vulnerability lookups.' This implies when to use the tool, and the sibling comparison (e.g., shodan-search-cves) reinforces its niche for CPEs rather than CVEs. However, it doesn't explicitly state when not to use it or name alternatives, which would merit a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It effectively discloses that the tool is free, requires no API key, and returns a specific result type (CveSearchResult) with a total count. It does not mention rate limits or error handling, but for a read-only search tool this is a reasonable level of transparency.

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 and front-loaded, with the core purpose in the first sentence. It includes useful additional details like the cost/free note and a return type line, but the return line is somewhat redundant given the existence of an output schema, so it could be slightly tighter.

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 main functionality, key filter options, and the cost/auth status, which is adequate for a search-oriented tool. However, it lacks differentiation from sibling tools (e.g., when to use this versus shodan-search), and does not mention any usage limits or background behavior, leaving some gaps in contextual guidance.

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?

All 7 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by explicitly naming the key filters (CISA KEV, EPSS, date range) which map to is_kev, sort_by_epss, and start_date/end_date, thus reinforcing their semantic meaning beyond just the parameter names.

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 'Search CVEs in Shodan's vulnerability database with powerful filters' and mentions specific capabilities like filtering by CISA KEV, sorting by EPSS, and date ranges. This distinct verb+resource combination differentiates it from sibling tools such as shodan-cve-lookup, which likely focuses on individual CVE lookup.

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 clear context by highlighting the tool's filtering strengths and explicitly noting it is free with no API key, which helps agents decide when to use it. However, it does not explicitly compare to alternatives like shodan-search or shodan-cve-lookup, nor does it state when not to use the tool.

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