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 states the tool retrieves API plan information, implying a read-only operation, but doesn't clarify if it requires authentication, has rate limits, returns structured data, or involves any side effects. For a tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly states what the tool does and includes specific details about the information retrieved, making it easy to parse and understand quickly.

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 complexity is low (0 parameters, no output schema), the description is minimally adequate. It explains what the tool does but lacks details on authentication needs, rate limits, or output format. With no annotations and no output schema, the description should provide more behavioral context to be fully complete for agent use.

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 tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description adds value by specifying what information is retrieved ('query credits remaining and scan credits'), which helps the agent understand the output context. Baseline for 0 parameters is 4, as it compensates for the lack of parameter details.

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: 'Get information about the current API plan including query credits remaining and scan credits.' It specifies the verb ('Get information') and resource ('current API plan') with concrete details about what information is retrieved. However, it doesn't explicitly differentiate from sibling tools like 'shodan_count' or 'shodan_query_search' which might also involve API usage tracking.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication status), timing (e.g., before making queries to check credits), or comparisons to sibling tools. This leaves the agent without context for tool selection in a workflow.

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 effectively describes key traits: it's a read-only operation (implied by 'get'), helps avoid wasting API credits (resource management), and works with facets for aggregated counts. However, it doesn't mention rate limits, authentication needs, or error handling, leaving some gaps for a tool with no annotation coverage.

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 sized and front-loaded with the core purpose in the first sentence. The example workflow and facet usage add value without being redundant. However, the 'Best Practice' section could be integrated more tightly, and some phrasing ('burning credits') is slightly informal, keeping it from a perfect score.

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 moderate complexity (2 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage guidelines, and behavioral context like API credit conservation. The main gap is the lack of output details (what the count result looks like), but with no output schema, this is a minor omission in an otherwise thorough description.

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 both parameters thoroughly. The description adds some context by mentioning 'Use with facets to see distribution without burning credits on full results,' which reinforces the schema's facet description, but doesn't provide significant additional meaning beyond what's in the structured fields. Baseline 3 is appropriate when schema does the heavy lifting.

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 specific action ('Get the total number of results for a search query') and resource ('search query'), distinguishing it from siblings like shodan_host_search by emphasizing it returns only counts, not actual results. The phrase 'without returning the actual results' explicitly differentiates its purpose from full search 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?

The description provides explicit guidance on when to use this tool ('Useful for scoping searches before running full queries to avoid wasting API credits'), when not to use it (implied: when you need actual results, use shodan_host_search instead), and includes a detailed example workflow with alternatives. The 'Best Practice' section reinforces this with specific scenarios like large ICS/SCADA queries.

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 describes the basic function but lacks critical details such as rate limits, authentication requirements, error handling, or the format of returned data. For a tool interacting with an external API like Shodan, this omission is significant and could lead to misuse.

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 a single, efficient sentence that directly states the tool's function without any fluff or redundancy. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly and understand the core 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?

Given the lack of annotations and output schema, the description is incomplete for effective tool use. It doesn't explain what the tool returns (e.g., IP addresses, error messages), how results are structured, or any behavioral nuances like pagination or rate limiting. This leaves gaps that could hinder an agent's ability to invoke the tool correctly in a real-world 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% description coverage, with the 'hostnames' parameter clearly documented as an array of strings. The description adds no additional semantic context beyond what the schema provides, such as examples of valid hostnames or constraints on the array size. This meets the baseline for high schema coverage but doesn't enhance understanding.

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 ('Perform DNS lookups') and resource ('domain names to IP addresses'), making it immediately understandable. However, it doesn't explicitly differentiate from its sibling 'shodan_dns_reverse', which likely performs reverse DNS lookups, leaving some ambiguity about when to use each tool.

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 no guidance on when to use this tool versus alternatives like 'shodan_dns_reverse' or other DNS-related tools. It states what the tool does but offers no context about appropriate use cases, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.

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 states the tool performs a 'lookup', implying a read-only operation, but does not specify whether it requires authentication, has rate limits, returns partial results on errors, or details the output format. For a tool with no annotations, this leaves significant behavioral gaps unaddressed.

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 a single, clear sentence that efficiently conveys the core function without unnecessary words. It is front-loaded with the essential information, making it easy to parse. Every part of the sentence earns its place by directly contributing to understanding the tool's 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?

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on usage context, behavioral traits, and output expectations. While it meets the minimum for a simple lookup tool, it does not provide a complete picture for effective agent use 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 schema description coverage is 100%, with the 'ips' parameter fully documented in the schema as an array of IP addresses. The description does not add any semantic details beyond what the schema provides, such as format constraints or examples. Given the high schema coverage, a baseline score of 3 is appropriate, as the description does not compensate but also does not detract.

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: 'Reverse DNS lookup to find hostnames associated with IP addresses.' It specifies the verb ('lookup'), resource ('hostnames'), and target ('IP addresses'), making the function unambiguous. However, it does not explicitly differentiate from sibling tools like 'shodan_dns_lookup', which likely performs forward DNS lookups, leaving some room for improvement in sibling distinction.

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 no guidance on when to use this tool versus alternatives. It lacks explicit instructions on when to choose it over siblings such as 'shodan_dns_lookup' or other DNS-related tools, and does not mention any prerequisites or exclusions. This absence of contextual usage information limits its helpfulness for an AI agent.

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 full burden for behavioral disclosure. While it mentions the tool is 'useful for finding known exploits' and 'critical for ICS/SCADA security assessments,' it doesn't disclose important behavioral traits like whether this is a read-only operation, potential rate limits, authentication requirements, or what format the results will be in. The description provides context but lacks critical operational details.

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 overly long and poorly structured. While the first two sentences are useful, the extensive lists of examples (ICS/SCADA Exploit Examples, Common ICS CVE Searches) could be condensed or moved to parameter documentation. The description front-loads the purpose but then includes redundant information that doesn't earn its place in the core description.

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 moderate complexity (3 parameters, no output schema, no annotations), the description provides adequate context about purpose and usage scenarios. However, it lacks information about what the tool returns (no output schema) and doesn't fully compensate for the absence of annotations regarding behavioral characteristics. The extensive examples help but don't complete the picture.

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 three parameters thoroughly. The description adds some value by providing extensive examples of query values (especially for ICS/SCADA contexts) and mentioning common facets for ICS, but doesn't add significant semantic meaning beyond what's already in the parameter descriptions. This meets the baseline of 3 when schema coverage is high.

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 as 'Search for exploits in the Shodan Exploits database' with specific verbs ('search', 'finding') and resources ('exploits', 'CVEs', 'software'). It distinguishes from siblings like shodan_host_search or shodan_query_search by focusing specifically on exploits rather than general host or query data.

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 when to use this tool ('Useful for finding known exploits for specific CVEs or software. Critical for ICS/SCADA security assessments') and includes extensive examples of ICS/SCADA-related queries. However, it doesn't explicitly state when NOT to use it or name specific alternative tools among 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the types of data returned but doesn't cover critical aspects like rate limits, authentication requirements, error conditions, or response format. For a tool that likely queries an external API with potential constraints, this is a significant gap in 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 efficiently structured in two sentences: the first states the core purpose, and the second enumerates the returned data. It's front-loaded with the main action and avoids unnecessary verbiage, though it could be slightly more concise by integrating the data list into the first sentence.

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 no annotations and no output schema, the description partially compensates by listing return data types. However, it lacks details on authentication, rate limits, error handling, and exact response structure. For a tool with two parameters and likely external API dependencies, this leaves gaps in completeness for safe and effective use.

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 clear documentation of both parameters (ip and history). The description adds marginal value by implying the 'history' parameter controls historical data inclusion, but doesn't provide additional context beyond what the schema already states. Baseline 3 is appropriate when the schema does the heavy lifting.

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 verb 'Get' and resource 'detailed information about a specific host by IP address', specifying the exact scope of data returned (services, open ports, vulnerabilities, historical data). It distinguishes from siblings like shodan_host_search (which searches rather than targets a specific IP) and shodan_dns_lookup (which focuses on DNS resolution rather than host 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 implies usage when you need detailed host information for a specific IP, but doesn't explicitly state when to use this tool versus alternatives like shodan_host_search (for broader searches) or shodan_dns_lookup (for DNS queries). No exclusions or prerequisites are mentioned, leaving some ambiguity about optimal use cases.

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 full burden and adds significant behavioral context beyond the input schema. It discloses that results include 'detailed information about discovered hosts including IP addresses, ports, services, and vulnerabilities' and mentions credit usage implications ('Use facets... without burning credits'). However, it doesn't explicitly mention rate limits, authentication requirements, or pagination behavior beyond the page parameter.

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 front-loaded with the core purpose and usage, but the extensive examples section (10 ICS examples + 3 patterns) makes it quite lengthy. While all content is relevant, it could be more concise by summarizing example categories rather than listing numerous specific queries. The structure is logical but not maximally 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 search tool with 3 parameters, 100% schema coverage, and no output schema, the description provides strong contextual completeness. It covers purpose, usage guidelines, practical examples, and behavioral aspects. The main gap is lack of output format details (what the return structure looks like), which would be helpful given no output schema exists. However, the description of return content ('detailed information about discovered hosts...') partially compensates.

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 substantial value by providing extensive ICS/SCADA examples and effective patterns that illustrate practical usage of the query parameter beyond the schema's general examples. It explains how to combine filters and use facets for aggregated results, giving semantic context that enhances understanding beyond the schema's technical specifications.

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 explicitly states the tool's purpose as 'Search Shodan for hosts matching a query' with specific resources (hosts) and detailed return information (IP addresses, ports, services, vulnerabilities). It clearly distinguishes from siblings like shodan_count (counts), shodan_dns_lookup (DNS resolution), and shodan_host_info (single host details) by focusing on multi-host search with query filtering.

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 explicit usage guidance: 'Use for asset discovery and reconnaissance' establishes the primary context. It differentiates from alternatives by focusing on host search (vs. shodan_api_info for API status, shodan_exploits_search for exploit data). The extensive ICS/SCADA examples and effective patterns section offer concrete when-to-use scenarios with specific query formulations.

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 describes what the tool does (returns a list of port numbers) and includes examples of key ports, which adds useful context. However, it lacks details on potential limitations, such as whether the list is static or updated, rate limits, or authentication needs, leaving gaps in 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 front-loaded with the core purpose, but it includes a lengthy list of example ports that, while informative, may be excessive for a concise tool definition. Every sentence adds value, but the structure could be more streamlined by integrating the examples more tightly or summarizing them, making it slightly less 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?

Given the tool has no parameters, no annotations, and no output schema, the description provides a good overview of purpose and usage. However, it lacks details on output format (e.g., list structure, data types) and doesn't address potential errors or behavioral nuances. For a tool with zero structured data, it's adequate but has clear gaps in completeness.

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 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't need to add parameter details, as there are none to explain. It provides value by listing example ports, which aids understanding, but since there are no parameters, a baseline of 4 is appropriate, as it compensates well for the lack of schema content.

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: 'Get a list of port numbers that Shodan crawls on the Internet.' It specifies the verb ('Get') and resource ('list of port numbers'), making it easy to understand. However, it doesn't explicitly differentiate from siblings like 'shodan_protocols' or 'shodan_host_search', which might also relate to port/protocol discovery, so it doesn't reach the highest score.

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 on when to use the tool: 'Useful for discovering what protocols are monitored' and 'Use this to verify Shodan monitors your target protocol.' This gives practical guidance. However, it doesn't explicitly mention when not to use it or name alternatives among siblings, such as using 'shodan_protocols' for protocol names instead of port numbers, so it falls short of a perfect score.

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 states the tool retrieves information, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, response format, or potential errors. For a tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It's front-loaded with the core function, making it easy to parse quickly. Every word earns its place, achieving optimal conciseness.

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 (0 parameters, no output schema, no annotations), the description is adequate but minimal. It covers the basic purpose but lacks details on behavioral traits like response format or usage context. For a tool in a set with many siblings, more guidance would improve completeness, but it's not entirely inadequate.

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 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't add parameter details, which is appropriate since there are none to explain. This meets the baseline for tools with zero parameters, as there's no need to compensate for missing schema information.

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: 'Get information about the protocols that Shodan supports for querying.' It specifies the verb ('Get information') and resource ('protocols that Shodan supports'), making the function understandable. However, it doesn't explicitly differentiate from sibling tools like 'shodan_ports' or 'shodan_api_info', which might also provide related metadata.

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 no guidance on when to use this tool versus alternatives. It doesn't mention context, prerequisites, or exclusions, such as whether this is for general reference or a prerequisite for other queries. With multiple sibling tools available, this lack of differentiation leaves the agent without clear usage instructions.

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 describes the tool's purpose and use cases but lacks critical behavioral details: it doesn't mention whether this is a read-only operation, if it requires authentication, rate limits, pagination behavior (beyond the 'page' parameter in schema), or what the output format looks like. For a tool with no annotation coverage, this is a significant gap in 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 appropriately sized and front-loaded: the first sentence clearly states the purpose, followed by bullet points for topics and use cases. Every sentence adds value, such as listing example queries and explaining benefits. It could be slightly more concise by integrating the bullet points into prose, but overall it's efficient with minimal 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?

Given the complexity (a search tool with community queries), no annotations, and no output schema, the description is incomplete. It covers purpose and usage well but lacks behavioral transparency (e.g., read-only status, authentication needs) and details on output format. For a tool with these gaps in structured data, the description should compensate more to be fully helpful.

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 both parameters ('query' and 'page') with descriptions. The description adds value by providing example query terms (e.g., 'SCADA', 'ICS') and context on what types of queries to search for, but it doesn't add syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 searches for saved Shodan queries shared by the community, which is a specific verb ('search') and resource ('saved Shodan queries'). It distinguishes from siblings like shodan_host_search or shodan_exploits_search by focusing on community queries rather than host data or exploits. However, it doesn't explicitly contrast with shodan_query_tags, which might be a related sibling.

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 on when to use this tool: for discovering popular query patterns, learning effective search techniques, and getting ideas for your own queries. It lists specific use cases like learning search patterns and finding vulnerability searches. However, it doesn't explicitly state when not to use it or name alternatives among the sibling tools.

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 describes what the tool returns (a list of popular tags) and hints at behavioral aspects like trending topics and common categories. However, it doesn't disclose critical details such as rate limits, authentication requirements, or whether the data is static or dynamically updated. The examples of tags (e.g., 'ics', 'scada') add useful context but don't fully cover behavioral traits.

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 well-structured and front-loaded with the core purpose in the first sentence. Each subsequent section (common tags and usage guidance) earns its place by adding practical value without redundancy. The bullet points for tags are efficient, and the overall length is appropriate for the tool's complexity.

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 (1 parameter, no output schema, no annotations), the description is largely complete. It covers purpose, usage, and parameter context adequately. However, without annotations or an output schema, it could benefit from more details on return format (e.g., structure of the tag list) or behavioral constraints, slightly reducing completeness.

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 its single parameter 'size', so the baseline is 3. The description adds value by providing context on the parameter's purpose: it mentions 'comprehensive tag list' when increasing size, which helps the agent understand the semantic impact beyond the schema's technical details. However, it doesn't fully explain trade-offs or limits, keeping it from a perfect score.

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: 'Get a list of popular tags for saved Shodan queries.' It specifies the exact resource (tags for saved queries) and distinguishes it from siblings like shodan_query_search (which searches queries) and shodan_host_search (which searches hosts). The mention of 'saved Shodan queries' differentiates it from other tag-related tools that might exist.

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 on when to use this tool: 'to browse popular query categories and discover new search angles.' It implies usage for exploration and discovery rather than direct querying. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the siblings, though the purpose differentiation helps infer alternatives.

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