sec-shodan-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.0.0
Disambiguation4/5
Most tools target distinct resources (DNS, search, host, scan, alerts, exploits, CVE, account) and descriptions clarify boundaries. However, pairs like shodan_cve_search vs. shodan_exploits_search and shodan_saved_queries vs. shodan_search_queries could cause minor misselection.
Naming Consistency3/5
Naming follows a loose shodan_<resource>_<action> pattern, but there are deviations: shodan_list_scans uses verb-first (list_scans) while shodan_alert_list uses resource-first (alert_list), and several tools are bare nouns (ports, filters, host). Terms like myip and cves_kev also break the convention.
Tool Count2/5
With 32 tools, the server feels bloated. Many are low-level utilities (shodan_myip, shodan_honeyscore, shodan_ports, shodan_protocols) that could be consolidated. The number exceeds the 25-tool threshold for 'too many' and makes the toolset harder for agents to navigate.
Completeness4/5
The toolset covers Shodan's core API well: search, host details, DNS, on-demand scans, alerts, exploits, CVEs, and account info. Minor gaps exist (e.g., no update alert, no cancel scan), but most workflows can be completed without dead ends.
Average 3.8/5 across 32 of 32 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
This repository is archived. Archived repositories automatically receive an F maintenance tier.
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no context beyond the annotations. While destructiveHint=true indicates the destructive nature, the description doesn't mention permanence, reversibility, or any side effects, which would be valuable for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single clear sentence. It is front-loaded and to the point, but it omits any helpful context, making it slightly too sparse for a destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with one parameter and no output schema, the description should at least note that the deletion is permanent or irreversible. The current text is functional but incomplete given the destructiveHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the only parameter (alert_id). The description adds no additional detail about the parameter, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a network alert'). It is unambiguous and distinguishes itself from sibling alert tools by the action, though it doesn't explicitly mention the ID parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like shodan_alert_create or shodan_alert_get. The context implies it's for removing alerts, but there are no explicit conditions, prerequisites, or warnings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, fully covering the safety profile. The description adds no behavioral context such as pagination behavior, rate limits, or what constitutes the 'directory'—it merely says 'browse'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It states the core action and resource concisely, which is appropriately sized for a simple read-only browse tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with strong annotations and full schema coverage, the description is minimally adequate. However, it lacks any context about how 'saved search queries' are organized or when to use browsing versus the sibling search tool, leaving some gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (page, sort, order) have meaningful descriptions. The description itself adds no parameter information, but according to the baseline for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Browse the directory of saved search queries' uses a specific verb (browse) and resource (directory of saved search queries), making the tool's purpose clear. However, it does not explicitly distinguish itself from the sibling tool 'shodan_search_queries', which likely provides search functionality over the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool vs alternatives. It does not mention that 'shodan_search_queries' should be used for searching, nor any other context for choosing browsing over searching. This is a clear gap given the large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the 'directory' framing but no additional behavioral context such as pagination behavior, result format, or whether the directory is public vs. user-specific.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler words, making it highly concise. However, its extreme brevity sacrifices potentially useful usage or differentiation context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the annotations cover the safety profile, but there is no output schema and the description fails to differentiate from the very similar sibling 'shodan_saved_queries'. The result format and intended use case are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'query' and 'page' are adequately documented in the schema. The description does not add extra parameter semantics or usage nuances beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Search') and resource ('directory of saved queries'), conveying the tool's basic purpose. However, it does not explicitly differentiate itself from the sibling tool 'shodan_saved_queries', so the agent must infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'shodan_search' or 'shodan_saved_queries'. There are no exclusions, prerequisites, or context clues beyond the bare statement of searching a directory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what the annotations already provide. It simply restates the purpose. It does not disclose return format, error behavior, authentication needs, or other limitations. Since the annotations already indicate a safe read operation, the description contributes little additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the tool's purpose without any waste. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with one required parameter and no output schema. The description is minimally adequate but fails to explain what 'details' means, what the return structure looks like, or any error cases. For its low complexity, a score of 3 is acceptable, though there is room for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single parameter alert_id (100% coverage), so the baseline is 3. The description does not add any extra meaning about the parameter, but the schema already provides sufficient clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 details for a specific alert.' It identifies the resource (alert) and action (get details). However, it does not explicitly differentiate from sibling tools such as shodan_alert_list or shodan_alert_delete, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you have a specific alert ID and need its details. There is no explicit mention of when to use it versus alternatives like shodan_alert_list, or any prerequisites or exclusions. This is implied usage only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. However, the description adds no behavioral context beyond the basic purpose—no mention of pagination behavior, output format, or API requirements—so it offers minimal transparency value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words, making it highly concise and well-structured for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature with full parameter documentation and safety annotations, the one-sentence description is minimally sufficient. However, it lacks context about return format or how to differentiate from similar CVE tools, making it slightly incomplete but not inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 3 parameters (skip, limit, maxResults) with descriptions, achieving 100% schema description coverage. The tool description adds no additional 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves CISA KEV catalog entries with a specific verb ('Get') and resource. This distinguishes it from sibling tools like shodan_cve_search or shodan_cve_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 any exclusions, prerequisites, or specific use cases, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'List', implying a read-only operation, but the annotations declare readOnlyHint=false, which indicates the tool may not be read-only. This is a direct contradiction. Additionally, no other behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence: 'List all active on-demand scans.' It is front-loaded, every word contributes, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple list operation with no parameters, but it lacks context about response structure or pagination. The contradiction with annotations further reduces its completeness, leaving the agent uncertain about the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. As per the baseline for zero-parameter tools, the description does not need to provide parameter details. The description adds no extra parameter semantics because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('active on-demand scans'), making its function unambiguous. It distinguishes itself from sibling tools like shodan_scan_status by focusing on listing all active scans rather than checking an individual scan's status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It lacks any mention of scenarios, exclusions, or comparisons to sibling tools such as shodan_scan_status or shodan_scan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the purpose. It does not disclose response format, potential side effects, authentication needs, or rate limits. Annotations are minimal (readOnlyHint: false), but the description adds no additional context about external behavior or safety, which is a notable gap for a tool with a simple but potentially non-read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately conveys the action and resource. Every word earns its place, and there is no redundancy, fluff, or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the status check returns (e.g., status values, progress states, or error indications). It only says 'check the status' without detailing the response structure, leaving the agent uncertain about how to interpret the result. It also lacks any mention of error conditions or what a scan ID refers to beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description already fully covers the only parameter (scan_id) with its source and type. The tool description adds no additional semantic meaning, so the baseline of 3 is appropriate given 100% schema coverage. The description neither enhances nor detracts from the schema's clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('check') and names the resource ('status of a previously submitted scan'), clearly distinguishing this tool from shodan_scan (submission) and shodan_list_scans (listing all scans). It is unambiguous and concise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after submitting a scan via shodan_scan, but it does not explicitly state when to prefer this tool over alternatives like shodan_list_scans, nor does it mention any exclusions or prerequisites beyond that implication. The context is present but not fully developed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds that CVEs are ranked by EPSS score, which is useful behavioral context, but it does not disclose other traits such as default ordering, pagination behavior, or response format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key action and resource. Every word contributes to understanding the tool's purpose with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain what the tool returns, but it only states 'CVEs ranked by EPSS score' without specifying return fields, pagination, or whether it returns full CVE objects or just IDs. For a tool with five parameters and no output schema, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all five parameters. The description does not add further semantic detail beyond the EPSS ranking context, making the parameter meaning purely schema-driven. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with resource 'CVEs ranked by EPSS score', clearly distinguishing it from sibling tools like shodan_cves_newest, shodan_cves_kev, and shodan_cve_search. It unambiguously states the tool's core functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when CVEs ranked by EPSS score are needed, but it does not explicitly state when to use this tool versus alternatives like shodan_cves_kev or shodan_cves_newest, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to restate these. However, it adds no additional behavioral context (e.g., rate limits, auth specifics, or response format), so it stays at a baseline level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundancy. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, but there is no output schema. The description only vaguely states 'account information' without enumerating typical fields (e.g., email, username), leaving the agent uncertain about the return structure. This is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so the baseline is 4. The description adds no parameter-specific meaning but does not need to, as there are no parameters to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('account information associated with the API key'), making it distinct from sibling tools like shodan_api_info. It is specific and unambiguous about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent without explicit decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds the purpose (monitoring IP ranges) but does not disclose side effects, authentication requirements, or expected response, which is acceptable given the simple create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise, front-loaded with the action, and contains no wasted words. It effectively conveys the tool's purpose in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, no output schema), the description covers the core action well. However, it does not mention what the response will look like or any follow-up steps (e.g., listing alerts), which could be helpful but is not critical for this simple creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter descriptions, including examples for 'ip' and types for 'expires'. The description does not add additional parameter semantics beyond what the schema already 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('network alert'), along with the purpose ('monitor IP ranges for changes'). This distinguishes it from sibling tools like shodan_alert_get or shodan_alert_delete, which manage existing alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when creating an alert to monitor IP ranges, but it does not explicitly state when not to use it or mention alternatives. Sibling tools are present, but no direct comparison is given, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds behavioral context by specifying chronological ordering ('most recently published'), which clarifies return order beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no filler. The core purpose is front-loaded, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description is adequate. The combination of description, schema, and annotations covers the essential facts, though a brief note about how it differs from shodan_cve_search could increase completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a descriptive entry for 'limit' (number of CVEs to return, default 10). The description does not need to repeat parameter details; it adds no parameter information but the schema handles it fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and names a distinct resource ('most recently published CVEs'), clearly distinguishing it from sibling tools like shodan_cve_lookup or shodan_cve_search. It is unambiguous about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like shodan_cve_search or shodan_cve_lookup. There is no mention of filtering, sorting, or the distinction between 'newest' and other CVE retrieval methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world safety. The description adds behavioral context by specifying the data sources covered (Exploit-DB, CVE, Metasploit), which helps set expectations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first gives the primary action, second adds scope. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with full schema coverage and read-only annotations, the description covers the core purpose and data scope. It doesn't detail return format, but the schema's 'detailed' and maxResults parameters imply structure; overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters (query, page, facets, detailed, maxResults) with descriptions. The tool description adds no additional parameter context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search the Shodan Exploits database' with a specific verb and resource. It adds scope by listing 'Exploit-DB, CVE, Metasploit, and more' but does not explicitly distinguish from sibling CVE-specific tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching exploit data but provides no explicit when-to-use or alternatives. Sibling tools like shodan_exploits_count and shodan_cve_search exist but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds minimal behavioral context beyond 'List all', but this is sufficient for a simple zero-parameter list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence with no filler or redundancy. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with no output schema, the description is adequate. It could optionally mention the filters' applicability to shodan_search, but that is not required for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so no parameter documentation is needed. The description correctly avoids mentioning parameters, aligning with the baseline 4 for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all Shodan search filters, using a specific verb and resource. This distinguishes it from sibling tools like shodan_search (performs searches) and shodan_facets (lists facets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor any context about how the filters should be applied. It simply states what it does without mentioning the use case or relationship to shodan_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a meaningful behavioral detail: it lists only 'active' alerts, not all alerts or alert history. However, it does not disclose additional behavior such as pagination, rate limits, or what qualifies as 'active', so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence of six words, front-loaded with the verb and resource. It contains no filler or redundant phrasing, making it extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with no output schema, the description fully captures the scope (all active alerts) and, with the annotations, the safety behavior. There's no missing information that would prevent an agent from using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. According to the rubric, 0 params grants a baseline of 4, and the description doesn't need to compensate for missing parameter info. It adds no parameter semantics because there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'active network alerts', making the operation explicit. It clearly distinguishes from sibling tools like shodan_alert_create (create) and shodan_alert_delete (delete) by focusing on listing existing active alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description doesn't mention when to use this tool versus shodan_alert_get, nor does it reference any alternatives or exclusions. The agent is left without context to decide between the various alert-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the word 'available' to suggest a fixed enumeration but provides no additional behavioral context. Since this is a simple read-only list, the annotation coverage is sufficient and the description modestly complements it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parametric-less read-only tool with solid annotations, the description is sufficiently complete. It lacks details about the output format or what constitutes a trigger type, but given the simplicity and presence of annotations, these are minor omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty with 100% schema description coverage. Per the baseline for 0-parameter tools, the schema fully documents the interface, and the description adds no param details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and clearly identifies the resource as 'available alert trigger types.' It distinguishes itself from sibling alert tools (create, get, delete) by focusing on the enumeration of trigger types, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to discover available trigger types, likely as a precursor to creating alerts, but it does not explicitly state when to use it versus alternatives or any exclusions. The use case is intuitive but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the CPE 2.3 format and matching semantics but does not disclose pagination behavior or result shape. This provides some value beyond annotations, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word is purposeful and directly conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool, the description plus schema is adequate: it specifies the required product parameter and optional pagination controls. It lacks details about the return format or empty-result behavior, but given the simplicity and full schema coverage, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage), including product, skip, count, and limit. The top-level description does not add any meaning beyond what the schema already states, so it meets the baseline but does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific action (look up), a specific resource (CPE 2.3 identifiers), and an input (product name). This clearly distinguishes it from sibling tools like shodan_cve_lookup, which focus on CVEs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when a product name needs to be mapped to CPE 2.3 identifiers. It does not explicitly mention exclusions or alternatives, but the context is unambiguous and sufficient for an agent to know when to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'forward DNS lookup' clarification, but it does not mention return format, rate limits, or other behavioral details. It is consistent with annotations and provides modest value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that presents the verb and resource first. There is no redundant information, making it exceptionally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only DNS lookup tool, the description, schema, and annotations together provide sufficient context. The only minor gap is not specifying the output format, but no output schema is provided and the core behavior is clearly communicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter with a concrete format and example. The description adds no additional parameter semantics. With schema description coverage at 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Resolve'), the object ('hostnames'), and the output ('IP addresses'). The parenthetical '(forward DNS lookup)' explicitly distinguishes it from the reverse DNS sibling (shodan_dns_reverse), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'forward DNS lookup' phrase implies when to use this tool (hostname→IP) versus a reverse lookup, but it does not explicitly name alternatives or state when not to use it. This is clear context without exclusions, meeting the criteria for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the context that facets relate to 'search result breakdowns,' which is useful. Yet it does not disclose return format, API key requirements, or rate limits. Thus moderate additional value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing only essential information. It avoids redundancy and is immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless metadata-listing tool, the description is adequate. It states what the tool returns (a list of facets) and its purpose. However, without an output schema, it could optionally elaborate on the nature of the facets, but this is not necessary for a tool this simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameter syntax. The baseline of 4 applies because there is no parameter semantics burden; the description correctly makes no parameter-related claims.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all facets available for search result breakdowns.' It clearly states the tool's action (list) and scope (facets for search breakdowns), distinguishing it from sibling tools focused on search, host, DNS, scans, alerts, and CVEs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies usage: call this to retrieve facet options before doing search result breakdowns. However, it does not explicitly contrast with alternatives like shodan_filters or mention when not to use it. Usage context is implied but not stated directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the scope of returned data (ports, services, etc.) but does not disclose any additional behavioral traits such as rate limits, response size, or historical depth beyond what the schema hints at. This meets the baseline but does not exceed it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loads the core purpose ('Get all information about a specific IP'), and every word contributes value. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only nature confirmed by annotations and a fully documented schema, the description is sufficient to set expectations for a basic lookup. It enumerates key data categories but does not detail output structure or pagination, which is acceptable since there is no output schema and the parameter descriptions already cover maxResults.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are fully described in the schema (coverage 100%), so the description adds no extra parameter meaning. The baseline of 3 applies because the schema already carries the burden, and the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all information about a specific IP, which is a distinct resource from sibling tools like shodan_search or shodan_dns_resolve. The verb 'Get' is specific and the scope is unambiguous, making the purpose immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use this tool: when you have a specific IP address and want comprehensive details. It does not explicitly name alternatives or provide exclusions, but the context is clear enough for an agent to select this over search-oriented siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds valuable context beyond annotations: each IP consumes 1 scan credit, which is a cost/rate constraint. It does not explain the asynchronous nature or return format, but the credit cost is a meaningful behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action. No unnecessary words or repetition. The credit cost is stated efficiently. This is an exemplary concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and clear annotations, the description is quite complete. It conveys the action, target scope, and a key constraint (credit cost). It does not mention that scans are asynchronous or that status can be checked via a sibling, but this is a minor gap given the tool's simplicity and the availability of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'ips', which is described with examples and format. The description adds no new parameter-specific information beyond what the schema already provides, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Request Shodan to scan') and clearly identifies the resource (specific IPs or CIDR ranges). It distinguishes the tool from siblings like shodan_search or shodan_host, which perform lookup operations rather than initiating scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool to initiate a scan. However, it does not explicitly state when to prefer this over alternatives or mention related tools like shodan_scan_status for checking scan results. No exclusions or alternative guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is clearly a safe read. The description adds useful context by specifying what information is returned (query credits, scan credits, limits), but does not disclose additional behavioral traits such as authentication requirements or rate limits. This adds some value without being rich, consistent with the calibration example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and outcome. Every word contributes meaning, with no fluff or repetition. It is concisely structured and immediately comprehensible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool, the description is complete. It states what the tool does and what it returns, which is sufficient given the lack of an output schema. The annotations cover safety, and no other contextual details are necessary for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no schema to explain. The description provides the tool's purpose and output content, which is sufficient given the lack of parameters. A baseline of 4 is appropriate for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('API plan info'), and enumerates the key contents (query credits, scan credits, limits). This distinguishes it from sibling tools that perform searches, DNS resolution, or scan management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context—use this tool when you need API plan information—but provides no explicit guidance on when not to use it or how it compares to alternatives. There is no mention of exclusions or references to sibling tools, so it falls at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral insight by specifying the return fields (CVSS, EPSS, references, affected products), which helps set expectations. No contradictions or unmentioned side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the action, the second lists return content. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool with read-only annotations, the description covers the purpose and return values sufficiently, even without an output schema. The mention of specific data types (CVSS, EPSS) gives enough context for an agent to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the sole parameter (cve_id) with format and example, so the description adds no additional syntactic detail. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Look up' and resource 'specific CVE by ID', clearly distinguishing it from sibling tools like shodan_cve_search which search by criteria. It also lists the returned data, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While not explicitly naming alternatives, the description makes clear this tool is for when you have a specific CVE ID, implying it is not for general search. The sibling tools' names (e.g., shodan_cve_search) provide context, but the description itself could be more explicit about when not to use it. This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safety profile. The description adds a meaningful behavioral detail—the mutual exclusivity of cpe23 and product—which is not captured in the annotations or schema. This goes beyond what annotations provide, though it does not fully describe pagination or output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the verb and resource, and every word adds value. The constraint is included without unnecessary elaboration, making it maximally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the search capabilities and the key constraint, but it does not mention return value shape (e.g., summaries vs. full CVE objects via 'detailed'), pagination, or date filters—though those are documented in the schema. Given the tool's moderate complexity and the absence of an output schema, the description is adequate but leaves the agent to infer output details and the distinction between filtering and sorting by EPSS.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 semantic value by naming the core filter categories (CPE, product, KEV, EPSS) and explicitly stating the cpe23/product incompatibility, which is not obvious from the schema alone. This helps the agent map high-level intents to the correct parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and identifies the resource ('CVEs') along with the main filter dimensions (CPE, product name, KEV status, EPSS score). This clearly differentiates it from sibling tools like shodan_cve_lookup (single CVE lookup) and shodan_cves_kev (KEV-only list), establishing a unified search capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit constraint that cpe23 and product cannot be combined, which is a useful usage rule. However, it does not mention when to use this tool versus the more specialized sibling tools (e.g., shodan_cves_kev for KEV-only queries), relying on the filter list to imply usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'Consumes 1 query credit', which is a useful behavioral constraint not present in annotations. It also notes the subdomain scope. However, it does not comment on pagination or result limits, though those are in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: one for purpose and one for cost. It is front-loaded and contains no filler, with every sentence adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple DNS lookup tool, the description covers purpose and cost, annotations cover safety, and the schema explains parameters. No output schema exists, but the description implies the return of DNS information. This is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full descriptive coverage of all parameters (domain, page, type, history, maxResults), so the description does not need to explain them. It adds no additional parameter semantics beyond the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'DNS information for a domain', and includes 'subdomains' as scope. This distinguishes it from sibling tools like shodan_dns_resolve and shodan_dns_reverse, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. While 'including subdomains' suggests it is for domain enumeration, it does not name alternatives or exclusion criteria. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the agent knows this is a safe read operation. The description adds no behavioral details beyond what these annotations convey (e.g., no response format, rate limits, or error behavior). It is consistent but adds minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource with zero unnecessary words. It is ideal for an AI agent to quickly parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter lookup tool with clear annotations and a complete input schema. The description fully conveys its purpose and distinguishing characteristic (reverse DNS) in a compact way. No output schema exists, but for such a simple read operation, the return value (hostnames) is self-evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers the only parameter ('ips' with description 'Comma-separated IP addresses'), and the tool description adds no additional parameter semantics. Baseline 3 applies because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('look up') and resource ('hostnames for IP addresses'), and explicitly labels the operation as 'reverse DNS lookup'. This clearly distinguishes it from the sibling tool shodan_dns_resolve, which likely handles forward lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The reverse DNS terminology provides clear context for when to use this tool (given IPs, needing hostnames), and the distinction from resolve is implied. However, it does not explicitly mention alternatives or state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this tool as read-only, open-world, and non-destructive. The description adds the return-value interpretation (0.0 = not a honeypot, 1.0 = honeypot), which is useful beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that front-load the action and output range. There is no redundant information or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter tool. The description fully states what it does, what it returns, and annotations confirm its read-only nature. The schema documents the required input, making the overall context complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter 'ip' with a description ('IP address to check'), and the tool description does not add any further 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Calculate') and resource ('probability that an IP is a honeypot'), and also defines the output range (0.0 to 1.0). This clearly distinguishes it from sibling Shodan tools that focus on host info, search, or scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case—assessing whether an IP is a honeypot—but does not explicitly state when to prefer this tool over alternatives like shodan_host or shodan_search, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral nuance that the IP is 'as seen by Shodan', implying it may differ from local or other perspectives, but it does not disclose network behavior, rate limits, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action and result. Every word contributes meaning, with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with comprehensive annotations and a self-explanatory output, the description provides sufficient context for correct invocation. The lack of an output schema is not an issue since the expected result is clearly stated as the public IP address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description carries no parameter burden. Per the rubric baseline for 0 parameters, a score of 4 is appropriate because there are no parameters for the description to explain, and it correctly focuses on the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('your current public IP address'), making the action immediately clear. The phrase 'as seen by Shodan' adds a distinguishing qualifier that separates it from sibling tools like shodan_search or shodan_host.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance or alternatives. However, as a zero-parameter utility, its use is implicitly obvious—call it to retrieve your public IP. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, covering the safety profile. The description adds no further behavioral context like pagination or return format, but is consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no superfluous words, perfectly front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is extremely simple with no parameters and no output schema. The description fully specifies what the tool does, and the return value (a list of ports) is inherently clear from the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The description adds no parameter details, but none are needed because the schema is empty and fully covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all ports that Shodan crawls on the Internet, using specific verb 'List' and resource 'all ports'. It distinguishes from siblings like shodan_protocols which list protocols, not ports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs to know which ports Shodan scans, but offers no explicit guidance on alternatives or when not to use. However, the purpose is so singular that the usage is reasonably implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral trait beyond the annotations: 'without consuming query credits,' which is not inferable from the schema or annotations. This gives useful context about cost and side effects, though it does not detail the response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, both relevant and free of filler. It front-loads the core action ('Count search results') followed by a practical benefit. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full schema coverage, and rich annotations, the description covers the essential aspects: what it does, when to use it, and a key behavioral trait (credit savings). There is no output schema, but 'Count search results' sufficiently implies the return type. The absence of explicit response format details is a minor gap given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both 'query' and 'facets' have descriptions). The tool description itself does not add any additional parameter-level meaning beyond what the schema already provides. Therefore, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Count search results.' It also highlights a key differentiator from sibling tools like shodan_search: 'without consuming query credits.' This makes the tool's purpose unambiguous and distinguishes it from alternatives in the same family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 scoping searches.' It also implicitly contrasts with shodan_search by noting the credits savings, suggesting when to choose this tool over a full search. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the filter syntax and the output format ('formatted host summaries'), which goes beyond the annotations and clarifies expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each earning its place: purpose, query syntax, and output format. No fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately conveys the main purpose, query syntax, and output type. It does not explain pagination or result limits, but those are covered by the schema. A more specific description of the returned summaries would push this to a 5, but the current level is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all six parameters, including query examples. The description's filter list overlaps with the schema's query example and adds minimal additional semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches Shodan for devices matching a query, using a specific verb and resource. It provides distinct scope ('devices') that differentiates it from sibling tools like shodan_exploits_search and shodan_search_queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for device discovery and provides filter examples for constructing queries, but it does not explicitly mention when to avoid this tool or name alternative tools. The 'devices' scope offers context that helps distinguish it from other Shodan searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the key behavioral trait that the tool returns only a count and not individual results, which helps set expectations. No contradictions exist, but it could mention response format or rate limits for fuller transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Count exploits matching a query' immediately conveys the action, followed by the caveat 'without returning individual results.' It is concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with robust schema coverage and clear annotations, the description adequately covers the operation and clarifies the output limitation. The verb 'Count' implies a numeric result, and the tool's low complexity means no additional context is necessary. The absence of an output schema does not create a gap here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters (query and facets), giving 100% schema coverage. The description adds no additional parameter-specific information beyond 'matching a query,' which is already implicit in the schema. Therefore, the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Count' and the resource 'exploits,' clearly stating the operation. The qualifier 'without returning individual results' distinguishes it from the sibling tool shodan_exploits_search, which likely returns detailed results. This makes the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without returning individual results' provides clear context that this tool is for count-only needs, implying that users wanting details should use a different tool. However, it does not explicitly name an alternative or provide explicit when-not-to-use guidance, so it does not fully meet the 5-level bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive, and the description adds useful context by specifying 'available for on-demand scanning,' clarifying the scope of the protocol list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that directly states the tool's function without extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple, parameterless nature of the tool, the description provides all necessary context. It is complete and unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and full schema coverage, the description does not need to explain parameters. The baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and the resource 'protocols' with the qualifier 'available for on-demand scanning,' clearly distinguishing it from other Shodan tools that list scans or ports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to know which protocols can be scanned on demand, but it does not explicitly state when to use this tool versus alternatives like shodan_ports or shodan_list_scans.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![sec-shodan-mcp MCP server](https://glama.ai/mcp/servers/schwarztim/sec-shodan-mcp/badges/card.svg)](https://glama.ai/mcp/servers/schwarztim/sec-shodan-mcp)

Score Badge

Copy to your README.md:

[![sec-shodan-mcp MCP server](https://glama.ai/mcp/servers/schwarztim/sec-shodan-mcp/badges/score.svg)](https://glama.ai/mcp/servers/schwarztim/sec-shodan-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/schwarztim/sec-shodan-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server