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

Annotations already indicate this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds the useful detail that 'default' selects email, but it does not explain permissions, what happens if the notifier is already attached, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single compact sentence with the main action front-loaded. The parenthetical hint is useful, though the description is arguably too terse for a two-parameter mutation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with two undocumented parameters and no output schema, the description is missing key context: what 'id' refers to, expected notifier ID format, permissions, and response behavior. It is not complete enough for fully confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no semantic descriptions for either parameter. The description only clarifies the special 'default' value for notifier_id and says nothing about what the 'id' parameter represents beyond being an alert identifier.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: attach a notifier id to an alert. It clearly differs from sibling tools like shodan_alert_remove_notifier, though it does not explicitly name that alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one narrow usage hint ('use default for email') but does not explain when to use this operation versus related tools such as shodan_alert_remove_notifier or shodan_notifier_create. No preconditions or exclusions are stated.

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

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

Annotations already disclose that this is a non-read-only, open-world, non-idempotent, non-destructive mutation. The description adds that the resulting alert continuously monitors for new services and vulnerabilities, which is useful behavioral context beyond the annotations, but it omits duplicate-alert behavior, permissions, rate limits, and response details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences and front-loads the monitoring purpose before the API body shape. It is efficient, though the body-shape sentence is potentially confusing rather than purely clarifying.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter mutation tool with annotations and no output schema, the description covers the main intent and field names. It still leaves out what is returned after creation (such as an alert ID), how duplicate alerts behave given non-idempotent behavior, and explicit alternatives, so it is only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, so the schema carries most parameter documentation. However, the description's indicated body shape places ip inside a nested filters object: { name, filters: { ip: [...] }, expires? }, while the input schema requires a top-level 'ip' property. This structural mismatch can mislead invocation even though the field names are mentioned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource clearly as monitoring an IP or netblock for new services and vulnerabilities, matching the create-alert concept, but it does not explicitly say 'creates an alert' and gives no sibling differentiation. An agent can infer the purpose from the name and title, but the description alone is slightly indirect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Monitor an IP or netblock for new services and vulnerabilities' implies when to use the tool, but there is no explicit guidance about when not to use it or which sibling tools (e.g. alert_update, alert_list) are alternatives. The usage context is adequate but incomplete.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, and the description's 'Delete' aligns with that safety profile. However, the description adds no detail about permanence, cascade effects on alert triggers/notifiers, or authentication requirements, so it does not enrich behavioral transparency beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Its brevity is structurally efficient, though it contributes to gaps covered under usage and parameter semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter delete tool whose annotations already flag destructiveness and idempotency, the core action and required id are clear enough to invoke. Still, the description omits where the id comes from and what exactly is removed, leaving meaningful context gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter is `id`, and schema description coverage is 0%, so the description is the only place that could explain its meaning or format. It merely repeats 'by id' without saying where to obtain the alert id or what format it takes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: delete a network alert. It is clear what the tool does, but it does not explicitly differentiate itself from neighboring alert tools such as update, get, or disable-trigger beyond the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to delete an alert versus updating, disabling, or inspecting it, and no prerequisites are stated. The only usable guidance is the implied 'delete by id' phrasing.

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

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

Annotations already declare that this is destructive, idempotent, non-read-only, and operates in an open-world context. The description adds no behavioral context beyond restating the action, such as whether disabling is reversible or what happens to the alert/trigger state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Its brevity is appropriate structurally, even though it leaves semantic gaps elsewhere.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation tool with two required parameters at 0% schema description coverage and no output schema, the description is too sparse. Annotations cover safety traits, but the agent still lacks parameter guidance and usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain either required parameter. The words 'alert' and 'trigger' loosely map to `id` and `trigger`, but the description gives no format, source, or expected value guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: disabling a trigger on an alert. It is clear enough to distinguish this from the sibling `shodan_alert_enable_trigger`, although it does not explicitly name the alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool, when not to use it, or which sibling to choose instead. The only implied usage is the obvious inverse of the tool name.

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

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

Annotations already declare non-readOnly, non-idempotent, non-destructive, so safety is partly covered, but the description adds nothing beyond the sentence. It doesn't say whether enabling replaces or appends to the existing trigger set, what happens to already-enabled triggers, or how invalid trigger names fail — all significant for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with zero filler, sized appropriately for a simple two-parameter call. It's terse to a fault rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and zero schema description coverage, the definition leaves the important unknowns unanswered: id semantics, replace-vs-append behavior on repeated calls, and error modes. An agent could invoke it but not confidently predict the effect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning. It does explain that 'triggers' is a comma-separated string (format not in the schema), but 'id' is never identified as an alert ID and no example trigger values are given.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Enable') and resource ('triggers on an alert'), which cleanly separates it from shodan_alert_disable_trigger and shodan_alert_triggers. It never names those siblings explicitly, but the verb+object combination is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus shodan_alert_disable_trigger, no prerequisite that the alert must already exist, and no pointer to shodan_alert_triggers for discovering valid trigger names. The agent must infer all of this.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the 'network alert' scope but no further behavioral context such as permissions or return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It is appropriately sized for a simple one-parameter retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With rich annotations and no output schema, the definition covers the basic call. However, it omits what an alert object contains and how the id is sourced, leaving minor gaps for an agent invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but 'by id' only restates the sole parameter name. It does not explain the expected id format or where an agent obtains a valid alert id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: get one network alert by id. That is clear enough to distinguish it from list/create/update/delete alert siblings, though it does not explicitly name an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'by id' implies the tool is used when an alert id is already known, but the description does not explicitly say when to use this instead of shodan_alert_list or how to obtain the id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that results are account-scoped, and says nothing about pagination, ordering, or the shape of an alert record – modest added value against an already-rich annotation set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, leading directly with the verb and resource. Nothing repeats the name or title verbatim beyond what is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description is the only place an agent could learn what a listed alert contains (id, triggers, notifiers) or whether results are paged. It provides none of that, leaving the return shape fully opaque – adequate for triggering the call, thin for consuming the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is empty, so there is no parameter semantics for the description to explain. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('network alerts') plus a scope ('on the account'), so an agent knows exactly what it returns. It does not explicitly differentiate from close siblings such as shodan_alert_get or shodan_alert_triggers, relying on the names alone for that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the phrase 'on the account' – an agent can infer this is the entry point for enumerating existing alerts before calling shodan_alert_get, update, or delete. But no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description is consistent with them. However it adds nothing beyond them — critically, it does not clarify whether detaching also deletes the notifier object itself or how existing trigger behavior is affected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with no waste, but it is terse to the point of under-specification for a destructive two-parameter mutation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A destructive, open-world mutation with no output schema and zero parameter descriptions needs more than one sentence; the agent lacks ID semantics, side effects, and confirmation of what the response contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so both 'id' and 'notifier_id' are undocumented strings. The description's vocabulary ('alert', 'notifier') hints at the mapping but never states which ID is the alert and which is the notifier, leaving real ambiguity for two required params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Remove' plus resource 'notifier from an alert' states the operation and scope clearly. It distinguishes itself implicitly from shodan_alert_add_notifier, though the inverse pairing is left for the agent to infer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to detach a notifier versus deleting it or using shodan_notifier_delete, and no prerequisites or alternatives named. The agent must 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safe read-only nature is well covered. The description adds that the returned trigger types are scoped to network alerts, but it does not describe the response shape or any rate-limit considerations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It immediately states the verb and the resource being listed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with rich annotations, the description is largely complete: the agent knows it retrieves trigger types applicable to network alerts. It could be slightly stronger by explicitly noting that the result feeds into enable/disable trigger operations, but no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to explain. Baseline score 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('trigger types that can be enabled on a network alert'), making the purpose clear. It implicitly distinguishes from shodan_alert_enable_trigger by focusing on enumeration rather than activation, but it does not explicitly name the sibling alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'that can be enabled on a network alert' implies this is a discovery step before enabling a trigger, but the description never states when to use this tool versus shodan_alert_enable_trigger or shodan_alert_get. No exclusions or alternatives are named.

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

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

Annotations already declare non-readOnly, non-idempotent, open-world, non-destructive, so safety is covered. The description adds only that fields are replaced, but does not clarify essential behavior: whether omitted optional fields (such as expires) are cleared or preserved, and whether triggers/notifiers on the alert survive the replacement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, but the brevity shades into under-specification for a 4-parameter mutation tool rather than being economically complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, non-idempotent tool with no output schema and zero schema description coverage, the description leaves too much unknown: partial-vs-full replacement semantics, parameter roles, and what an agent should expect after the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, yet it only gestures at "name/filters." It never explains what `id` refers to, that `ip` is a filter value, or what `expires` means (and its interaction with a replace-semantics operation).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Replace the name/filters on an existing alert" gives a specific verb and resource, and the name distinguishes it from shodan_alert_create/list/get/delete. It never explicitly contrasts with those siblings, but the mutation intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this rather than recreate an alert or delete-and-create, no prerequisites (alert must already exist), and no mention that at least one notifier or trigger must be configured. The agent must infer all of this.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context that the response concerns the authenticated account and three specific credit/plan fields, but it does not describe rate limits or response formatting; with annotations present, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence that states what the tool returns without any filler. Every element, including plan, query credits, and scan credits, earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only tool with rich annotations and no output schema, the description is largely complete: it identifies the authenticated context and enumerates the returned credit/plan data. The only minor gap is that it does not describe the exact shape of the plan information, though that is not required for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is empty, so there are no parameter semantics to explain. This is the baseline 4 case: the description does not need to compensate for any undocumented input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ("Show") and names the resource ("authenticated plan, query credits remaining, and scan credits remaining"), so the tool's purpose is clear. It does not explicitly differentiate itself from sibling account/profile tools such as shodan_profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states that the plan is "authenticated," which implies an API-key prerequisite, but it gives no explicit guidance on when to use this tool versus alternatives. There are no when-not conditions or named sibling comparisons.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description nonetheless adds two non-obvious behavioral facts: no query credits are consumed and no host records are returned, both of which materially affect how an agent budgets calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the outcome, then the constraints, then the usage directive. No filler and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter read tool with full annotation coverage and no output schema, the essential facts (cost, return nature, ordering relative to search) are present. The gap is query and facet syntax, which an agent still has to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, but it only names 'query' and 'facets' without explaining query syntax (Shodan filters), facet format (comma-separated list), or expected values. Optionality of facets is already conveyed by the schema's required list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource: return how many banners match a query, plus facets. It also delimits scope by saying it does not return hosts, which cleanly separates it from shodan_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this before shodan_search" gives an explicit sequencing rule and names the sibling alternative. It stops short of covering other alternatives such as shodan_search_facets or when to skip counting entirely, so it is clear but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful operational context ('Free, no API key', CVEDB source) but says nothing about result size, pagination, or what happens when no CPE matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler; the core action and input are front-loaded before the cost/source note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should at least sketch the return value (a list of CPE 2.3 strings) and pagination via skip/limit. Annotations are rich enough to cover the safety profile, but the parameter and return-shape gaps keep it at minimum viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the burden and it only addresses the required 'product' input implicitly. The skip and limit parameters are completely undocumented in both schema and description, leaving pagination behavior unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('look up') plus a precise resource ('CPE 2.3 identifiers') and an input qualifier ('for a product name'), with a named source (CVEDB). It is clearly distinguishable from CVE/exploit siblings like shodan_cve and shodan_exploits, though it does not explicitly say how it relates to them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No indication of when to choose this over siblings such as shodan_cve or shodan_cves, nor that its typical role is resolving a product name into a CPE before a CVE lookup. 'Free, no API key' describes cost/auth, not when to use the tool.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely non-annotated context: the data source (Shodan CVEDB), that it is free and requires no API key, and which enrichment fields come back. It doesn't cover rate limits or response shape, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the resource, source, and returned fields; no filler and nothing that could be trimmed without losing signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter lookup with no output schema, an agent has enough: what it queries, the source, the identifier format, and the field families returned. The one missing piece is how this relates to the sibling shodan_cves list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema itself documents the CVE-YYYY-NNNN format, so the description carries no additional parameter burden. Baseline 3 applies since the schema does all the parameter work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('look up') and resource ('a CVE in Shodan CVEDB') and enumerates the data categories returned (CVSS, EPSS, KEV, CPEs, references). It does not, however, differentiate itself from the sibling shodan_cves, which an agent must infer is the list/browse counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the name and the 'free, no API key' note, but there is no explicit statement of when to pick this over shodan_cves, shodan_cpes, or shodan_exploits. The closest thing to guidance is the cost/auth aside rather than an alternative selection rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds auth context ('Free, no API key') and a parameter conflict rule, which is helpful, but omits pagination, rate-limit, and return-behavior details. It adds some value beyond annotations but is not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly written sentences, front-loaded with search modes and key constraints. Every sentence carries signal—filters, free access, and mutual exclusivity—with no redundant restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter search tool with no schema descriptions and no output schema, the description covers the core query and two important filters. However, it omits pagination, date-bound, and count/limit semantics, so it is adequate for basic invocation but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 9 parameters. The description explains product, cpe23 format, KEV filtering, EPSS sorting, and product/cpe23 exclusivity, but leaves skip, count, limit, start_date, and end_date undocumented. It only partially compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the verb 'Search' and resource 'CVEDB', plus the two query modes: product or CPE 2.3. This clearly identifies a CVE search tool, but it does not explicitly name or differentiate from siblings like shodan_cve or shodan_cpes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives useful context ('Free, no API key') and a mutual-exclusivity rule ('Do not pass product and cpe23 together'), but does not state when to use this tool versus shodan_cve or when to choose product over cpe23. Usage is implied rather than explicitly routed.

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

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

Annotations already cover the safety profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds that listing is scoped to a named bulk dataset, but does not disclose return format, pagination behavior, authentication needs, or dataset-name discovery.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It states the action and scope efficiently, though the brevity contributes to other gaps.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity read-only tool with annotations covering safety and one required parameter, the description is minimally adequate. Without an output schema, however, it should say more about what 'files' means and what the listing returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema does not document the single dataset parameter. The description partially compensates by saying it is a named bulk dataset, which identifies the parameter as a dataset name, but it gives no format, example, or source for valid names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: list files inside a named bulk dataset. It implicitly distinguishes itself from shodan_datasets by saying files are inside a dataset, but it does not explicitly name that sibling or otherwise differentiate the pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, prerequisites, or alternatives. It never mentions shodan_datasets as the way to discover dataset names, so the agent must infer the relationship between the two tools.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful account-scoping context ("available to the account") but does not mention pagination, rate limits, or return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no redundant or filler content. Every word contributes to stating the action and scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with rich safety annotations, the description is minimally adequate. However, it does not clarify the relationship to shodan_dataset_files or describe the return shape or pagination, leaving some gaps for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides no parameter semantics to explain. The description need not compensate for missing parameter documentation, and baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("List bulk data filesets") and adds the account-level scope. It is clear enough to distinguish from most sibling tools, but it does not explicitly differentiate itself from the related shodan_dataset_files tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is a listing operation but gives no guidance on when to use it versus alternatives such as shodan_dataset_files. There are no exclusions, prerequisites, or contextual triggers.

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

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

Annotations already declare this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful context that results are what 'Shodan knows' rather than live DNS resolution, but it omits pagination behavior and what history=true changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is as concise as possible while still stating purpose and scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and four parameters, the description is too thin: it does not explain pagination, the DNS type filter, or historical results. It also does not clarify the return shape beyond 'subdomains and DNS records'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across four parameters, and the description only implicitly covers domain. It does not explain page, type, or history, which are significant for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('subdomains and DNS records') scoped to a domain, so the core purpose is clear. It does not explicitly distinguish itself from DNS siblings such as shodan_dns_resolve or shodan_dns_reverse.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no guidance on when to use this tool instead of the DNS resolve/reverse siblings, nor any prerequisites or exclusions. The only implied usage is that it returns Shodan-known DNS data for a domain.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so safety is covered. The description adds no behavioral context beyond input format — nothing about how unresolvable hostnames are reported, batch limits, or rate limiting, which matters for an open-world lookup service.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the operation and followed by the input format; nothing is wasted. It is arguably too terse for the remaining gaps, but on structure and brevity alone it is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only lookup with annotations covering safety, the minimum is present. Missing are the failure semantics (what happens to a hostname that doesn't resolve) and any hint about response shape, which would help since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter is a bare string with only minLength, so the description's 'comma-separated list' is genuinely additive — it tells the agent the string is a batch container rather than one hostname. It still lacks constraints such as maximum entries or accepted hostname syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Resolve hostnames to IPs', which is unambiguous on its own. It does not, however, distinguish itself from the inverse sibling shodan_dns_reverse or from shodan_dns_domain, so an agent must infer the direction/scope distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage information is input formatting ('comma-separated list'). There is no guidance on when to use this versus shodan_dns_reverse, whether batches are preferred over single lookups, or limits on list size.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description contributes only the batching detail (comma-separated list) and says nothing about rate limits, behavior on unresolvable IPs, or result format — modest added value over the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero waste, and the core purpose is front-loaded before the input-format note. Nothing could be cut without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should say something about the returned shape (e.g., IP-to-hostname mapping) and how unresolvable IPs appear — neither is covered. For a simple lookup tool with good annotations this is adequate but noticeably thin on the return side.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single `ips` parameter is an undescribed string, so the description's "comma-separated list" is genuinely load-bearing and conveys multi-IP input that the schema cannot. It stops there, though — no guidance on limits, whitespace, or invalid entries — so it only partially compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Resolve IPs to hostnames" gives a specific verb and resource, making reverse DNS clearly distinct from forward lookups like shodan_dns_resolve or shodan_dns_domain. It never names those siblings explicitly, so differentiation relies on the agent's own inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states what the tool does but gives no when-to-use framing, no prerequisites, and no mention of the closely related shodan_dns_resolve or shodan_dns_domain siblings. The agent must infer that this is the reverse-DNS path when it holds IPs rather than hostnames.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and idempotency are covered; the description's added value is disclosing that the response is a count rather than a result set. It says nothing about how the count is returned, whether facets alter the return shape, or any cost/credit implications of a count query against an open-world API.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb first and zero filler. It is efficient, though its brevity leaves the parameter burden entirely unmet rather than deliberately deferred.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With two undocumented parameters, no output schema, and an open-world API, the description should at minimum explain what `query` accepts and what `facets` does. An agent could call it, but only by guessing at query syntax and ignoring facets.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning and it does not. The required `query` is only obliquely referenced ('matching exploits') with no hint that it is a Shodan search filter string, and the optional `facets` parameter is never mentioned at all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Count matching exploits') and adds a scope qualifier ('without returning the full result set') that implicitly separates it from shodan_exploits. It stops short of naming the sibling explicitly, so differentiation requires inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without returning the full result set' implies when to use this over the full-result sibling, but there is no explicit 'use this when you only need a total' statement and no exclusions or prerequisites. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the API-key authentication requirement, which is genuinely new context beyond the annotations and matters for invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the resource first and the API-key caveat close behind. Nothing is wasted, though it is arguably under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With three undocumented parameters, no output schema, and no mention of pagination behavior for page or what facets does, the description leaves substantial gaps for an agent trying to invoke the tool correctly. Only the query-filter hints partially fill the void.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions the page or facets parameters. It does add meaningful context about the query string's filter fields (cve, type, platform, port, author), which is a real contribution the schema lacks, but two of three parameters remain undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (Shodan Exploits archive), which is clearer than the terse title. It doesn't distinguish itself from siblings like shodan_exploit_count or shodan_cve, but the archive name gives an agent enough to identify the right resource family.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only guidance is a prerequisite ('requires API key'). There is no statement of when to use this versus shodan_exploit_count, shodan_cve, or the general shodan_search, and no indication of query syntax expectations.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds useful behavior beyond that by disclosing the output semantics — a probability bounded 0.0–1.0 with the endpoints explained — which is valuable since there is no output schema. It says nothing about rate limits, auth, or what happens on an unknown IP.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence with the resource front-loaded and the return range appended, so every clause carries information. The garbled leading token ('Labs') is a small defect but does not cost comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-argument, no-output-schema tool the description covers purpose and return range adequately. It is thin on input format and error behavior, which is the remaining gap for an agent calling it blind.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden, and it does say the input is an IP. However, it adds no format detail (IPv4 vs IPv6, CIDR not accepted, whether a hostname works), which matters for a single unconstrained string parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('honeypot probability for an IP') and even the scale, so the agent knows exactly what it returns. It does not differentiate from siblings (e.g., shodan_host, shodan_internetdb), which keeps it below a 5, but the siblings are heterogeneous enough that confusion is unlikely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as shodan_host or shodan_internetdb that also describe an IP. The agent must infer the use case 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.

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description still earns credit by adding two things annotations cannot: the default output shape (compact analyst summary of org, ports, products, vulns) and the crucial cost fact that host lookups do not spend query credits. It omits whether results are cached or how quickly the record changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero waste: purpose first, output-mode switch second, cost caveat third. Every sentence carries information an agent needs and nothing is repeated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does part of the job by characterizing both return shapes (compact summary contents vs. raw banner record). Combined with full schema coverage and rich annotations, an agent can call this correctly, though the effect of history and include_raw on the returned payload is only implied by their schema strings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented, which sets the baseline at 3. The description adds meaning only for `summary`, clarifying that the compact card contains org, ports, products, and vulns, and leaves minify, history, and include_raw entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Look up an IPv4/IPv6 address in Shodan') plus the two response modes, so an agent immediately knows this is a single-host lookup. It does not name a sibling (e.g. shodan_search or shodan_internetdb) to sharpen the boundary, but the per-host scope is inherently distinct from the fleet-wide search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to leave the default summary on versus setting summary=false for the raw banner record, which is genuine usage guidance. It offers no guidance on when to pick this over shodan_internetdb, shodan_honeyscore, or shodan_search for a given IP, and gives no exclusions, so selection against alternatives is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description earns credit for adding non-obvious traits beyond them: no API key required, weekly staleness of data, and no banner data returned. These materially shape expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence plus a scope note, both front-loaded with the essentials (source, fields, keylessness, staleness) and no wasted phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly enumerates return fields (ports, CPEs, hostnames, tags, CVE ids) and flags data limitations. Only the absence of an explicit sibling comparison keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'ip' parameter, so the baseline is high; the description adds value by supplying the comma-separated list limit (max 25), which the schema itself does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('IP enrichment from internetdb.shodan.io') and enumerates the returned fields. The 'Free, keyless' framing implicitly distinguishes it from key-based siblings like shodan_host, but it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'free, keyless' hints at when to prefer this over paid host lookups, and the max-25 list cap is a practical constraint. There is no explicit when-to-use/when-not or named sibling alternative such as shodan_host.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the meaningful nuance that the address is Shodan's observed vantage point rather than a local interface, but says nothing about rate limits or whether the result can change between calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. Every word (public, Shodan sees, this client) carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only lookup with full annotation coverage and no output schema, the description tells the agent everything needed to call it. Only minor gap is not hinting at the return shape (a bare IP string) or that it reflects egress address.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the schema has nothing to explain; baseline is 4. The description correctly implies no inputs are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (return) and resource (public IP address) with the important qualifier that it is the address Shodan sees for this client, not a local interface address. Clearly distinct from sibling lookup tools like shodan_host or shodan_dns_resolve.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call with no arguments to learn your external IP. No explicit when-to-use/when-not guidance or named alternatives (e.g., using shodan_profile for account info), but the tool is narrow enough that ambiguity is low.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=true, so the safety profile is covered. The description adds the useful convention that provider-specific fields belong in args and gives an email example, but says nothing about authentication, return values, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and followed immediately by the most important argument convention. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with a free-form nested args object, the description is thin. It omits the relation to alerts, how to discover providers, and what happens on success; with no output schema, that missing return context matters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It meaningfully explains the nested args object with an example, but does not clarify where valid provider values come from or what the top-level description parameter is used for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a notifier.' It is distinguishable from sibling read/delete/list notifier tools by name, but the description never explains what a notifier is (e.g. a notification channel used by alerts), so an agent new to Shodan must infer its role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this versus shodan_alert_add_notifier or shodan_notifier_providers. It also omits the obvious prerequisite of discovering valid providers first, leaving usage entirely implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds no behavioral context beyond 'by id' – it does not mention irreversibility, required permissions, or effects of deleting a notifier that may be attached to alerts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. However, its brevity reflects under-specification rather than efficient completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive mutation tool with no output schema, and the description says nothing about return behavior, side effects, or whether deletion affects alert configurations. For a delete operation, the definition is too sparse to be fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the only parameter, id, is undocumented in the schema. The description saying 'by id' identifies the parameter's role but does not explain the expected identifier format, where to obtain it, or error behavior for invalid ids.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: delete a notifier by id. It is clear what the tool does, though it does not explicitly distinguish itself from sibling notifier tools such as shodan_notifier_get or shodan_notifier_create.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no warning about when deletion should be avoided. Usage is only implied by the word 'Delete'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that — no note on behavior when the id is unknown, no auth/scope requirements, no indication of what a notifier object contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with zero filler and the identifier constraint front-loaded. It is efficient, though its brevity borders on under-specification rather than tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter read with annotations covering safety, this is close to adequate. However, with no output schema, the description should at least hint at what a notifier record returns (provider, config, id), which it omits entirely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter and schema description coverage is 0%, so the schema gives just type and minLength. The description's 'by id' confirms the parameter is the notifier identifier, which is marginally useful, but it adds no format hints (e.g., whether ids are numeric strings or UUIDs) to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get one notifier') plus the lookup key ('by id'), which distinguishes it from the list tool shodan_notifiers. It does not explicitly name the create/delete siblings, but the singular 'one ... by id' scope is clear enough for an agent to pick it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this instead of shodan_notifiers or shodan_notifier_providers, and no prerequisites (e.g., needing a known notifier id). Usage is only inferred from the word 'Get'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds that it returns both providers and their required arguments, which is useful output context, but provides no further behavioral details (e.g., rate limits, auth needs, format).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no wasted words, front-loading the verb and resource. It is appropriately sized for a simple zero-parameter list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter discovery tool with annotations and no output schema, the description is nearly complete. It tells what is listed and that arguments are included, though it could clarify the return format (e.g., whether arguments are strings, types, etc.) to fully compensate for the missing output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so no parameter semantics are needed. With schema coverage at 100% (trivially) and no params, the baseline of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('notifier providers') and adds that it returns required arguments. This distinguishes it from siblings like shodan_notifiers (which likely lists configured instances) and shodan_notifier_get, but does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus shodan_notifiers, shodan_notifier_get, or other siblings. No exclusions or prerequisites are mentioned; usage must be inferred 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.

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is fully covered. The description adds the useful detail that results are scoped to the calling account (implying auth), but says nothing about return shape, pagination, or ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, and the resource plus scope are front-loaded. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only list tool whose annotations cover the behavioral profile, this is nearly complete. The only gap is that there is no output schema, so a brief hint about what a notifier record contains (id, provider, service) would have closed the loop.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case; there is nothing parameter-wise the description needs to explain, and the schema is trivially complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List') and resource ('notifiers') with an explicit scope ('configured on the account'), which separates it from create/delete/get siblings by name alone. However, it doesn't explicitly call out the distinction from shodan_notifier_get or shodan_notifier_providers in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, prerequisites, or named alternatives. The agent must infer from the verb that this is the discovery step before shodan_notifier_get or shodan_alert_add_notifier, but nothing in the description states that relationship.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds one useful behavioral nuance — membership is per-API-key and may be absent ('if any') — but says nothing about what the membership payload contains or the no-org case.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste. It is arguably too terse given the tool's context, but every word earns its place and nothing is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description is the only source of return-value context, and it gives only a one-line hint ('membership ... if any'). An agent can call it safely thanks to the annotations but cannot anticipate the response shape or the empty-result case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies, and the schema being an empty object is consistent with the description's claim that membership is derived from the API key rather than passed in.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('organization membership') scoped to the current API key. It is clearly distinct from siblings like shodan_api_info or shodan_profile, but it does not explicitly contrast itself with them, leaving the agent to infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus shodan_profile, shodan_api_info, or shodan_my_ip, and no stated preconditions or exclusions. The agent must guess whether 'organization membership' overlaps with those sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The word 'currently' usefully implies a live, dynamic dataset, but there is no mention of API credit cost, caching, or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler, which is appropriate for a zero-argument lookup. It is arguably too terse for the value it could add, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does not say what a returned port entry contains (port number, protocol, count) or how large the result is. For a simple zero-param tool that is a modest, not fatal, gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is an empty object at 100% coverage, so there is nothing for the description to compensate for. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: list ports that Shodan crawlers scan. This is distinguishable from shodan_protocols and shodan_services by the crawler-scan framing, though the description never names those siblings to sharpen the line.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus shodan_protocols, shodan_services, or shodan_search_filters, and no prerequisites or exclusions. The agent must infer the use case entirely from the one-line purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scoping context by noting the configured API key, but it does not mention rate limits, authentication details, or what the profile response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single, front-loaded sentence with no filler. Every word contributes to identifying the operation and its API-key scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, zero-parameter, read-only tool with rich annotations, the description is sufficient for correct invocation. It is slightly incomplete because it does not describe what fields the profile includes, and there is no output schema to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to document. Per the rubric, a zero-parameter schema establishes a baseline of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: returning the Shodan account profile. It also scopes the result to the configured API key. However, it does not explicitly distinguish this from related siblings like shodan_api_info or shodan_my_ip.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The intended usage is only implied by the tool name and description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds only the mild signal that this is a static enumeration of supported protocols rather than a live scan, and says nothing about auth needs, rate limits, or whether the list is static or version-dependent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is as short as it can be, though the terseness leaves 'protocols' slightly ambiguous without a clarifying clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-arg reference list with no output schema, the description is nearly sufficient. A short note on the return shape (e.g. a list of protocol name strings) would close the remaining gap, since no output schema exists to document it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the description carries no parameter burden and the baseline is 4. Nothing in the text misleads about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'List' plus the resource 'protocols available for on-demand Internet scans' specifies what the tool returns. It is distinguishable from data-returning siblings like shodan_ports and shodan_services in that it is a catalog rather than scan output, though the description never states this contrast explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'available for on-demand Internet scans' implies the result feeds shodan_scan or shodan_scan_internet, but no sibling is named and there is no when-to-use/when-not statement. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The only added behavioral signal from the description is that results are community-shared rather than private, which is a modest but real contribution beyond structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, which is structurally clean. However, the brevity reflects under-specification rather than tight economy given three undocumented parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should convey what a returned query looks like and how pagination behaves, and it does neither. For a listing tool with three unannotated parameters, the definition leaves out information an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for three parameters, so the description should compensate, but it never mentions page, sort, or order. Even the enum choices (votes/timestamp, asc/desc) are left for the agent to discover in the raw schema without any explanation of defaults or effect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ("List shared community search queries"), and the qualifier "shared community" distinguishes it from the personal/saved-query sibling shodan_query_search. It stops short of explicitly naming that sibling, but the scope is clear enough to identify the tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this instead of shodan_query_search or shodan_query_tags, and no mention of prerequisites or pagination context. The agent must infer usage entirely from the one-line purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond them: it doesn't say what a search matches against (tags, text, author), whether results are paginated, or how the community directory behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste, but its brevity comes from under-specification rather than tight editing; it leaves obvious questions unanswered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, two undocumented parameters, and three near-identical query-related siblings, the description should explain result shape and how it differs from shodan_query_list. It does neither, so an agent cannot confidently select or invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Two parameters with 0% schema description coverage, so the description must carry the load and doesn't. It never explains whether 'query' is a free-text search term, a tag, or an exact name match, nor what 'page' paginates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb (Search) and a resource (community query directory), which is more than a tautology. But it doesn't distinguish this from the sibling shodan_query_list, so an agent can't tell which one retrieves the directory versus which one searches within it. Purpose is only vaguely delimited.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this instead of shodan_query_list or shodan_query_tags, both of which appear to operate on the same query directory. The description provides no conditions, exclusions, or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds little beyond that, only clarifying the scope as the 'community query directory', but does not disclose return format, pagination, or what 'popular' means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, existing annotations covering safety, and no output schema, the description is adequate but incomplete. It omits any explanation of the 'size' parameter and does not describe what the returned tags look like, leaving minor gaps for an agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one optional parameter 'size' with 0% description coverage, and the description does not mention it at all. The parameter's meaning is somewhat inferable from its name, but the description fails to compensate for the complete lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List popular tags') and scopes it to the 'community query directory', distinguishing it from query-focused siblings like shodan_query_list and shodan_query_search. It is clear what the tool does, though it does not explicitly name the sibling alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. Usage is only implied by the purpose statement.

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

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

Annotations declare the write-ish, open-world, non-idempotent profile, and the description adds high-value context beyond them: one scan credit per IP, paid plan requirement, and the two-step confirmation gating. It omits that scans are asynchronous and results must be fetched elsewhere, which is the main missing behavioral note.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, zero filler, with the core action first and the hard requirements immediately after. Every sentence carries a constraint an agent needs before calling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should explain that a scan is queued asynchronously and results come from shodan_scan_status. It covers cost/auth/gating well but leaves the caller without a picture of what happens after invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description ties confirm to credit spend and confirms the /24 threshold for confirm_large, giving semantic weight the schema alone only hints at. The 'each IP spends 1 scan credit' line is genuinely additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (crawl IPs/CIDRs on demand) and is distinguishable from read-only siblings like shodan_host or shodan_search. It doesn't explicitly name which sibling to use instead of shodan_scan_internet, but the scope here is clearly user-supplied targets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete gating rules: confirm=true required, confirm_large=true for CIDRs wider than /24, paid plan required. It stops short of saying when to prefer this over shodan_scan_internet or shodan_host, but the conditions for a successful call are explicit.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds valuable gating information about enterprise access and double confirmation, but does not explain consequences, duration, cost, or rate limits of an internet-wide crawl.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the enterprise restriction and followed by the confirmation requirements. There is no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex internet-wide crawl operation with four required parameters, no schema descriptions, and no output schema. The description covers eligibility and confirmation but omits critical operational context such as expected runtime, output shape, and usage limits, leaving too much for the agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning. It names the target concept ('one port/protocol') and says both confirm flags must be true, but it does not explain what each confirmation flag distinguishes, what protocol strings are valid, or what port values mean beyond the schema's bare integer type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'crawl the Internet for one port/protocol.' The 'Enterprise-only' qualifier and internet-wide scope help distinguish it from targeted scan siblings such as shodan_scan, though no alternative is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides an eligibility restriction ('Enterprise-only') and explicit prerequisites ('Requires confirm=true and confirm_internet=true'), which are useful context. However, it does not say when to prefer this over shodan_scan or shodan_search, nor does it state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the account-scoping detail; it says nothing about pagination, result limits, or what fields are returned. With annotations carrying the burden, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with zero waste, front-loading the verb and resource and following with the scoping constraint. Nothing extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with full annotation coverage and no output schema, the description is nearly complete. The only gap is the lack of pagination/result-size guidance, which is minor but could matter for an agent deciding how to page through scan listings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, and the schema coverage is 100%, so there is nothing for the description to disambiguate. This is the baseline case where no parameter explanation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (List) and resource (on-demand scans) with a useful scope qualifier ('submitted by this account'), which distinguishes it from shodan_scan (scan submission) and shodan_scan_status. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiating.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the retrieval tool for previously submitted scans, but there is no explicit 'use this when...' or mention of shodan_scan_status/shoden_scan alternatives. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that this retrieves progress, but does not mention response shape, polling behavior, or rate limits, which would be useful context for a status-check tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence, front-loaded with the action and resource, with no filler. It is appropriately sized for a simple status-retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only tool with annotations and no output schema, the description is minimally adequate. However, it does not describe what progress information is returned or whether the scan may still be pending, which would help an agent interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter has 0% schema description coverage, so the schema only says it is a required string called 'id'. The description compensates partially by clarifying it is an on-demand scan id, but does not specify the ID format or where it comes from.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ("Get progress") and resource ("on-demand scan id"), so it is clear this checks status rather than starting or listing scans. However, it does not explicitly distinguish itself from siblings like shodan_scans or shodan_scan, leaving some ambiguity for an agent comparing scan-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning an on-demand scan id, but gives no explicit guidance on when to call this versus shodan_scans, shodan_scan, or shodan_scan_internet. An agent must infer the selection criteria.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real context the annotations lack: when a credit is consumed (filters present or page > 1) and that the default response is compact match rows.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no waste. The core action, example, credit rule, and alternative are all front-loaded in that order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the action, query syntax, cost model, default response shape, and a sizing alternative, which is a lot for a tool with no output schema. Facet/field usage and the 100-page cap remain undocumented, keeping it short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, so the description should compensate more than it does. It explains the query string syntax and the page>1 credit trigger, but leaves facets, fields, minify, and summary unexplained in both the schema and the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Search') and resource ('Shodan's banner database') and gives a concrete query example ('apache country:DE'). It also names the sibling it defers sizing to (shodan_count), so an agent can place it among the many Shodan tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends 'Prefer shodan_count to size a query first,' giving a clear when-to-use-an-alternative rule. It does not, however, distinguish this from similar search siblings like shodan_query_search or shodan_search_facets.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=true, destructive=false, so the safety and purity profile is fully covered. The description adds only that facets summarize results and says nothing about return shape or whether the list is static or account-dependent, which is modest added value against a lower annotation-aware bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence with zero filler; the resource and its role are stated immediately. Nothing could be removed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param read tool with full annotations, the definition is close to complete, but it omits the crucial follow-on context: that the returned facet names are then passed to the search/count tools as facet parameters. Without that, an agent knows what the tool returns but not how the output is consumed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter text is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List facet names') plus the qualifier that they summarize search results, so an agent knows it is a discovery/enumeration endpoint. It does not distinguish itself from close siblings like shodan_search_filters or shodan_search_tokens, which could easily be confused with facets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'that can summarize search results' implies it belongs in a search workflow, but no explicit when-to-use, when-not, or alternative (e.g., shodan_search_filters vs. shodan_search_tokens) is named. Usage is only weakly inferable.

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

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

The annotations already declare read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds no behavioral detail beyond the purpose statement, such as return shape, ordering, or scope of the filter list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single front-loaded sentence with no filler. Every phrase contributes to identifying the resource being listed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only lookup, the description is nearly complete: it states that the result is filter names accepted in Shodan search queries. The only minor gap is that it does not clarify how the list relates to sibling query-building tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero input parameters, so the baseline is 4. The description does not need to explain parameter usage because the schema has an empty properties object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a clear verb ('List') and resource ('filter names accepted in Shodan search queries'), so the agent can understand the core operation. It does not explicitly distinguish this from sibling tools such as shodan_search_facets or shodan_search_tokens, which also relate to query-building metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that the tool helps discover search-query filters, but it gives no explicit when-to-use guidance, prerequisites, or comparison with alternatives. It never says whether an agent should call this before shodan_search, or instead of shodan_search_facets.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds the useful implication that parsing precedes and avoids paid API calls, but it never states explicitly that no Shodan credits/network call are consumed, nor what the parsed result looks like beyond the three bucket names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler; the action is front-loaded and the motivating use case follows immediately. Nothing redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description reasonably enumerates the result components (filters, attributes, free text), which is enough for an agent to know what to expect. It could add a note on error behavior for malformed queries, but the core is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single 'query' parameter, so the description would need to compensate. It only implies the input is a raw Shodan query string, offering no syntax, filter-format, or quoting guidance, leaving the schema to speak for itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Break a Shodan query into...') and names the output decomposition (filters, attributes, leftover free-text), which distinguishes it from shodan_search and shodan_search_filters. It falls short of 5 because it doesn't explicitly contrast itself with the search/execute sibling it is meant to precede.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Useful to verify query syntax before spending credits' gives a clear trigger condition (pre-flight validation before a paid search). It stops short of naming alternatives such as shodan_search_filters or shodan_query_search, so the agent must infer the routing itself.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds only that the data is a port-to-service map from Shodan crawlers; it does not discuss freshness, completeness, rate limits, or response shape beyond the one-line purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. That is appropriately terse for a zero-parameter lookup tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter lookup with rich annotations, the description identifies the returned mapping but omits routing guidance and any explicit statement of response format. It is adequate, but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to compensate for. This matches the baseline of 4 for parameter-free tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource—a mapping from port to named service—and scopes it to Shodan crawlers, so the agent knows what data it returns. However, it does not distinguish this lookup from sibling reference tools such as shodan_ports or shodan_protocols, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance or comparison to alternatives. The only context is 'for Shodan crawlers,' which does not tell the agent whether to call this instead of shodan_ports or another sibling reference tool.

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