greynoise-mcp-server

Official

by GreyNoise-Intelligence

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Server Quality Checklist

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

Latest release: v0.5.4
Disambiguation5/5
Each tool has a distinct, clearly defined purpose. BSI, alert, blocklist, session, and GNQL tools have unique suffixes that differentiate them, and the descriptions leave no ambiguity about what each tool does.
Naming Consistency4/5
Most tools follow a verb_noun pattern with hyphens (e.g., export-sessions-pcap, lookup-ip-context). However, a few tools like session-fields, session-timeseries, and callback-overview start with nouns, breaking the pattern. Overall, conventions are mostly consistent.
Tool Count2/5
With 28 tools, the set exceeds the 25-tool threshold for 'too many.' While each tool serves a specific need, the count feels heavy for a single server, and several stats tools could potentially be combined with a parameter.
Completeness3/5
The read-side is very complete—IP context, sessions, GNQL, BSI, callbacks, alerts, and blocklists are well-covered. However, there is no tool to create or delete alerts or blocklists, which is a notable lifecycle gap for management workflows.
Average 4/5 across 27 of 28 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 21 commits in the last 12 weeks
- Last stable release on July 22, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true. Description adds only 'current list', which is redundant with 'retrieve'. No disclosure of behavior beyond annotations (e.g., that the list may change, that size parameter limits results, or that results may be paginated). With annotations covering safety, the description contributes little.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with verb and resource. However, it could be slightly more structured with a hint about required parameter or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and clear annotations, the description provides minimal but functional coverage. It omits when to use the tool relative to siblings and does not mention that a blocklist_id is required, which is critical context for a 3-parameter tool with one required field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described (size maximum, blocklist_id type, workspace_id default). Description does not add any extra meaning or context for parameters. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve the current list of IPs in a blocklist' – a specific verb and resource. It distinguishes from sibling 'list-blocklists' (which lists blocklists) and 'list-callback-ips' (which lists callback IPs). However, it does not mention the required blocklist_id parameter explicitly, missing an opportunity to reinforce purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it doesn't say 'Use this to get IPs for a specific blocklist; for listing all blocklists, use list-blocklists.' The agent must infer usage from sibling names and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, which the description does not contradict. The description adds behavioral details such as hourly bucketing and ISO 8601 time format, but does not elaborate on the open-world nature or potential unknown results beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with four sentences, each serving a distinct purpose: stating the action, explaining utility, specifying time format, and detailing the size parameter. No redundant information, and key points are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, time format, and size constraints, but it does not explain what happens when start_time or end_time are omitted (since they are optional). The output schema exists and may compensate, but the description leaves a gap in understanding default behavior for time bounds.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all four parameters. The description adds an example of ISO 8601 format and clarifies size constraints (default, max), but these are already present in the schema. The description does not add significant new semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves hourly GNQL records for a time range, specifying it is for temporal analysis of IP activity. It distinguishes the tool from its sibling 'gnql-timeseries-stats' by focusing on records rather than statistics, but does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is useful for investigating when IPs were active, but it does not provide guidance on when to avoid using it or compare it with other sibling tools like 'gnql-stats' or 'gnql-metadata-query'. No explicit when-to-use or when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds no extra behavioral details. It merely states 'list', which is consistent but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return values are covered elsewhere. However, the description does not mention that workspace_id defaults to the bound API key workspace, which is only in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters adequately. The description does not add any parameter information beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'blocklists' within a workspace, distinguishing it from siblings like 'get-blocklist-ips' and 'update-blocklist'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get-blocklist-ips' or 'list-alerts'. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context (e.g., permission requirements, side effects, error states). Given annotation coverage, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It efficiently communicates the tool's purpose while remaining minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, 100% schema coverage, and an output schema, the description's minimalism is partly justified. However, it lacks any summary of side effects, return value, or usage notes. Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema sufficiently documents all 6 parameters. The description merely lists fields already in the schema and adds no additional meaning, interactions, or constraints. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Update') and resource ('blocklist'), and explicitly lists the modifiable fields (query, name, IP limit, enabled state). This clearly distinguishes the tool from siblings like 'list-blocklists' (listing) and 'get-blocklist-ips' (reading IPs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites, exclusions, or context for usage. The description only states what it does, which is insufficient for an AI agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds the requirement for BSI entitlements, which is useful behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core purpose and constraints with no extraneous content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are covered. The description is sufficient given the tool's simplicity (one optional parameter). It explains the data grouping and entitlement requirement, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a full description of the date parameter including pattern and default. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides counts of BSI IPs and CIDRs grouped by category, and mentions required entitlements. It distinguishes effectively from sibling tools like bsi-company-stats or bsi-trust-stats, which group by different criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only notes that BSI entitlements are required. It does not provide guidance on when to choose this tool over siblings like bsi-company-stats or bsi-trust-stats, nor does it mention any scenarios where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent, not read-only, not destructive. Description adds minimal behavioral context, e.g., no mention of prerequisites or behavior if already enabled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle action with full param coverage and output schema present, the description is adequate though minimal. Missing context about idempotency? But annotations cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Enable' (or 'resume') and the resource 'alert', distinguishing it from siblings like get-alert, list-alerts, update-alert.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for previously disabled alerts, but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives like update-alert.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating safe, standalone operation. The description adds that the output is a 'plain list', which is helpful but does not disclose additional behavioral traits (e.g., output format specifics, pagination, or limits). With annotations present, the description adds moderate context but not rich detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and output type. The reference to 'Same filters as List Callback IPs' is efficient but slightly dependent on external knowledge. Overall, it is concise and structured well, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 optional parameters, many sibling tools, and an output schema (present but not detailed), the description provides basic context ('plain list', date format). However, it misses details on how the export is delivered (e.g., file or stream) and any limits. The output schema reduces the burden, leaving completeness adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 12 parameters with descriptions (100% coverage). The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline for high coverage without enhancing semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export', the resource 'callback/C2 IPs', and the output format 'plain list'. It explicitly distinguishes from the sibling tool 'List Callback IPs' by mentioning shared filters, providing specific and actionable purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exporting filtered IPs, referencing 'Same filters as List Callback IPs', but does not explicitly state when to use this tool versus alternatives like exporting sessions or searching. No when-not or alternative guidance is provided, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by specifying the batch size limit (10,000) and the return structure. However, it does not disclose potential errors, rate limits, or how invalid IPs are handled, which would be useful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, front-loading the key capability (batch check) and then listing outputs. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (context signal true), the description adequately covers inputs and expected outputs. It could be improved by mentioning error handling or performance considerations for large batches, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the only parameter ('ips') thoroughly, including format and constraints. The description adds no additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Check up to 10,000 IP addresses'), the resource ('IP addresses'), and the specific outputs ('classification, business-service status, trust level, summary breakdown'). This uniquely distinguishes it from sibling IP tools like 'lookup-ip-context' which handles single IPs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'lookup-ip-context' for single IPs). It does not mention circumstances where this batch check is appropriate or any prerequisite actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the requirement for BSI entitlements, which is beyond annotations. However, no other behavioral traits (e.g., rate limits, output format) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two clear sentences with no extraneous information. It is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description is sufficient for a simple read-only tool. It states the main function and a requirement. Some context about trust levels or data scope might be helpful but is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; the 'date' parameter is fully described in the schema, and the description makes no additional reference to parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool counts BSI IPs and CIDRs grouped by trust level, using a specific verb and resource. It distinguishes from sibling tools like bsi-category-stats and bsi-company-stats, which group by different dimensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Requires BSI entitlements' as a prerequisite, but does not provide explicit guidance on when to use this tool versus alternatives. Usage is implied by the title and the existence of sibling tools, but no when-not-to-use or alternative suggestions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive and idempotent behavior. The description adds 'pause' and 'without deleting' but does not further elaborate on side effects or states. The bar is lowered due to annotations, but some extra context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no unnecessary words. Front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with good schema coverage and an output schema, the description is mostly complete. However, it does not mention that the alert must exist or what happens if already disabled, but this is minor given the annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions. The tool description adds no additional meaning to the parameters, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Disable (pause)' and the resource 'alert'. It distinguishes from the sibling tool 'delete-alert' by explicitly saying 'without deleting it'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to pause an alert without deletion) but does not mention when not to use, such as when the alert is already disabled, nor does it list alternative tools like 'enable-alert' or 'update-alert'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a side effect: 'Saves the binary to a temp file and returns its path'. This adds behavioral context beyond annotations (readOnlyHint=false, openWorldHint=true). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that covers all essential information: action, resource, options, side effect, and a constraint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and an output schema (assumed), the description adequately explains the output (temp file path) and the demo scope limitation. It could briefly mention the return format structure, but overall is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all parameters. The description adds minimal extra meaning, reaffirming the type enum and default pcap. It does not provide new semantic details beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Download a single session's data'), the resource ('for a given session ID'), and the output formats ('PCAP or raw payload'). It distinguishes from sibling tools like 'export-sessions-pcap' by specifying 'single session'. The constraint 'Not available when scope=demo' adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint ('Not available when scope=demo') but does not explicitly state when to use this tool versus alternatives like 'export-sessions-pcap' or 'get-session'. No context on when to choose pcap vs raw formats or when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint. Description adds retrieval by ID, which is partially redundant with schema. Doesn't disclose error behavior or response format beyond what annotations hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, concise sentence with no unnecessary words. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Description is sufficient for a simple retrieval tool, though it could mention error cases for invalid IDs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented. Description adds no new meaning beyond 'by ID'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Retrieve', resource 'blocklist's configuration', and mechanism 'by ID'. It distinguishes from sibling tools like list-blocklists (multiple) and get-blocklist-ips (IPs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when needing a single blocklist by ID, but lacks explicit guidance on when not to use it or alternatives. No comparison with list-blocklists or other retrieval methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and openWorldHint=true. Description adds little beyond the title, but no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste. Perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and output schema. Description is sufficient given low complexity and rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with full schema description coverage. Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb ('List') and resource ('alerts configured in a workspace'). Distinguishes from siblings like 'get-alert' (single alert) and mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives mentioned, but simple read-only list context is implied by readOnlyHint annotation and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds 'fast, lightweight' but does not disclose additional behavioral traits such as rate limits, data sources, or any side effects beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, front-loaded with key information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, output schema exists (not shown but present), and annotations cover read behavior, the description is sufficient. It could mention the return type but is not required due to output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter 'ip' is thoroughly defined with format, pattern, and description. The description adds no extra meaning beyond 'single IP address', so the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'classification and business-service check for a single IP address'. It is specific and distinguishes from siblings like multi-ip-check (multiple IPs) and callback-ip-lookup (different purpose).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage with 'fast, lightweight' but does not explicitly state when to use this tool versus alternatives like lookup-ip-context or bsi-lookup. No exclusions or criteria provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds that the tool returns 'nodes + links', which is consistent and provides some output context. However, it does not disclose any additional behavioral traits such as aggregation behavior, cardinality limits, or that it operates on aggregated data rather than raw sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no redundant or verbose language. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, graph output), the description covers the core concept well. The presence of an output schema reduces the need to explain return values. However, it lacks details on default parameters (e.g., max_nodes=100, src_field=source.ip) and aggregation semantics, which would be helpful for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it only mentions 'source field and destination field' in general terms. No additional parameter guidance or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a connection graph between source and destination fields over a time range, using a specific verb ('build') and resource ('connection graph'), and adds the use case 'visualizing communication relationships'. This distinguishes it from sibling tools like session-unique-values or search-sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for visualizing communication relationships but does not explicitly state when to use this tool versus alternatives, nor does it provide conditions when not to use it. No exclusions or sibling references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no additional behavioral context beyond listing updatable fields. It does not contradict annotations, but it does not enrich the agent's understanding of side effects (e.g., whether updates trigger notifications).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 14 words, front-loading the action and objects. No extraneous information. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested schema (schedule, recipients) and an output schema (context indicates presence). The description is minimal, but the schema fully covers parameters and return values. It adequately informs the agent about the tool's scope, though it could mention that all required fields (alert_id, name, query, schedule, recipients) must be provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already described in the input schema. The tool description adds no new meaning beyond the schema, merely echoing field names (query, schedule, etc.). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an alert's query, schedule, recipients, name, or enabled state' clearly states the verb (update) and the specific resources (alert fields). It distinguishes from sibling tools like 'enable-alert' (which likely only toggles enabled state) and 'get-alert' (read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists what fields can be updated but does not explicitly state when to use this tool vs. alternatives like 'enable-alert' or 'get-alert'. It lacks guidance on context or prerequisites, leaving the agent to infer from the field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool saves a binary PCAP to a temporary directory and returns the file path, which adds context beyond annotations. The annotations include readOnlyHint:false (indicating mutation) and openWorldHint:true, which align with the description. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three sentences, each serving a distinct purpose: stating the action, detailing the behavior, and providing usage examples. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but indicated), the description does not need to explain return values. It adequately covers the main purpose, output location, and query syntax. For a tool with 7 parameters and 2 required, the description is complete enough for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the input schema already provides descriptions for all 7 parameters (100% coverage), the description adds value by giving concrete examples of Lucene query syntax for the 'query' parameter. This enhances understanding beyond the schema alone. Other parameters are not elaborated further, but the baseline is 3 due to high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it exports a PCAP file from GreyNoise sensor sessions and returns the file path. It uses a specific verb ('Export') and resource ('PCAP file from sessions'). However, it does not explicitly differentiate from sibling tools like 'export-session-data' or 'search-sessions', which limits clarity for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to export PCAP files matching query criteria) and provides guidance on using Lucene query syntax with examples. However, it does not mention when not to use it or suggest alternative tools for different needs, such as when only session data is needed instead of PCAP.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation, indicating a read-only operation. However, it adds no extra behavioral context beyond what annotations already provide (e.g., no mention of output format, pagination, or rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key information. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema, the description is sufficiently complete. It clearly communicates the tool's purpose and input requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions. The description adds no additional meaning beyond 'by ID'. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (retrieve), the resource (alert configuration), and the method (by ID). It effectively distinguishes from sibling tools like list-alerts (which returns multiple) and update-alert (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an alert ID and need its configuration, but it does not explicitly state when to use this tool versus alternatives like list-alerts or update-alert. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-idempotent, non-destructive action. The description adds the plan requirement and the basic behavior (runs query, notifies), but does not provide deeper behavioral details such as rate limits, idempotency guarantees, or consequences of creating an alert. With annotations present, the description adds some value but is not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains two sentences that are front-loaded and to the point. No extraneous information. Every word contributes to the purpose and prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with a rich schema (7 parameters, nested objects, output schema), the description covers the core purpose and prerequisite. The output schema documents return values, so the description does not need to elaborate. Minor omission: it does not mention that workspace_id defaults to the bound workspace, but that is in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents each parameter. The description only restates that the alert 'runs a GNQL query', which is already in the schema. It adds no additional semantic meaning or examples beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'scheduled alert', and what it does ('runs a GNQL query and notifies recipients'). It distinguishes itself from sibling tools like list-alerts, update-alert, etc., which perform different actions on alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Requires a plan entitled to alerts'), which provides usage context. However, it does not explicitly state when to use this tool vs alternatives like update-alert or delete-alert, though the tool name and purpose imply its usage for creation only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint false, destructiveHint false, etc.) and the description adds useful behavioral context: the blocklist auto-populates dynamically and requires a specific plan. This goes beyond what annotations provide, clarifying the resource nature and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that first state the purpose and then add a key prerequisite. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description does not need to explain return values. It covers the creation action, parameter semantics (via schema), and the prerequisite. It is sufficiently complete for the tool's complexity and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes all five parameters. The description adds some meaning to the query parameter (dynamic, auto-populates) but does not significantly enhance understanding of other parameters beyond their schema descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a dynamic blocklist from a GNQL query, using specific verb 'create' and resource 'blocklist'. It distinguishes from sibling tools like 'update-blocklist' and 'list-blocklists' by emphasizing the dynamic nature and query-based population.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite (requires a plan entitled to blocklists) but does not provide guidance on when to use this tool versus alternatives like update-blocklist or when not to use it. It lacks explicit context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context by stating the deletion is permanent and cannot be undone, which reinforces the irreversible nature beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the purpose and critical behavior. Every sentence is necessary and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with output schema present and comprehensive annotations, the description is sufficiently complete. It could mention what is returned, but output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema already explains parameters. The description adds no additional parameter details. Baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Permanently delete an alert', clearly identifying the verb (delete) and resource (alert). It distinguishes from sibling tools like create-alert, update-alert, enable-alert, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting alerts but does not explicitly state when to use this tool versus alternatives like disable-alert or update-alert. No guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds valuable context about permanence ('cannot be undone'), which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the action and its permanence. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of annotations, the description covers essential behavioral aspects. However, it could mention side effects on related resources (e.g., blocklist entries) for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already fully documented. The description adds no additional meaning to the parameters beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (delete) and resource (blocklist), and distinguishes from siblings like create, get, update. The phrase 'Permanently delete' adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like disabling a blocklist. The warning 'This cannot be undone' implicitly advises caution but lacks explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds value by detailing the specific data categories returned (classification, tags, raw scan data, business service intelligence, geo, network metadata), which are not covered by annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action and lists all relevant data types. No redundant information; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input, read-only annotations, and existence of an output schema, the description provides a comprehensive overview of the return data. Minor omission: could mention potential rate limits or authentication requirements, but these are likely covered by the API context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single required 'ip' parameter and a clear description in schema. The tool description does not add parameter-specific details beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'detailed GreyNoise context for a single IP', and explicitly lists the types of data included (classification, tags, intelligence, geo, network). This sets it apart from sibling tools like 'multi-ip-check' which handles multiple IPs, and session/alert tools which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a single IP lookup and hints at the rich data returned, but does not explicitly instruct when to use this tool over siblings like 'multi-ip-check' or 'get-session'. There are no 'when-not' or alternative recommendations, leaving the agent to infer context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and open-world behavior, which the description confirms. Beyond annotations, the description adds that results are paginated and lists the types of fields returned (source/destination IPs, ports, timestamps, byte/packet counts, classification), providing useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loading the core purpose and return information. Every word contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (indicated), the description adequately covers the tool's purpose, parameters, and return fields. It mentions pagination and the required time range, missing only minor defaults like page size, which are in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited value beyond the schema. It mentions Lucene query syntax for the 'query' parameter, but otherwise relies on the schema for parameter details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Query and filter') and resource ('GreyNoise sensor network sessions') with specific return fields. It distinguishes from siblings like 'get-session' (single session) and 'export-session-data' (export) by focusing on search/filter across a time range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using Lucene query syntax and a time range, but does not explicitly state when to use this tool versus alternatives (e.g., 'get-session' for a single session, 'export-session-data' for bulk export). Usage context is implied but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and openWorldHint, and the description adds the entitlement requirement. No further behavioral traits are needed; it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the purpose and a constraint. Every word is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description adequately covers the purpose and a critical requirement. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and fully describes the `date` parameter. The description adds no additional parameter information, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it counts BSI IPs and CIDRs grouped by company name, which is a specific verb and resource. It distinguishes from sibling tools like bsi-category-stats and bsi-trust-stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions a prerequisite (BSI entitlements) but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives. Usage is implied by the verb and grouping, but no sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds rich behavioral context beyond annotations by detailing the exact return categories (attack stage, scanner associations, RIOT status, geo/network enrichment, downloaded malware files). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loaded with the main action, followed by a precise list of return fields. No wasted words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has one simple parameter and an output schema (not shown but indicated). Description fully explains what the tool does and what it returns, with no gaps. Annotations cover safety. Complete for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'ip', which is described as 'The callback IP address to look up'. The description does not add further parameter-level detail, but the high schema coverage meets the baseline. Description clarifies the return types, indirectly supporting parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a specific verb ('Look up') and resource ('single callback/C2 IP'), then enumerates return fields like attack stage, scanner associations, RIOT status, geo/network enrichment, and downloaded malware files. This clearly distinguishes it from siblings like 'list-callback-ips' (list) and 'quick-check-ip' (simpler check).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for individual lookups via 'single callback/C2 IP', but provides no explicit context about when to use this tool versus alternatives like 'multi-ip-check' or 'bsi-lookup'. No when-not-to-use or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true. The description adds context about pagination, date format (YYYY-MM-DD), and filter options, which goes beyond the annotations by clarifying the tool's operational behavior (e.g., paginated, filterable).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that front-loads the purpose and then efficiently lists filter categories. Every word earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 optional parameters) and the presence of an output schema, the description adequately summarizes the tool's functionality. The output schema covers return values, and the annotation indicates safe read-only behavior, so no further behavioral details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so schema already documents all 14 parameters. The description adds marginal value by grouping filters into categories (attack stage, dates, file attributes, scanner associations) and specifying date format, but does not explain parameter interaction or defaults beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'paginated list of callback/C2 IPs' with specific filters (attack stage, dates, file attributes, scanner associations). It distinguishes itself from sibling tools like 'lookup-ip-context' or 'get-blocklist-ips' by focusing on filtered, paginated lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing IPs with various filters but does not explicitly mention when to use this tool versus alternatives (e.g., lookup-ip-context for single IP details). No guidance on exclusions or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint (safe read) and openWorldHint (data not authoritative). The description adds valuable behavioral context: IPv6 is rejected, results are in ascending precedence order (lower = higher priority), and a license is required. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three short sentences that convey purpose, ordering, constraint, and license requirement. Every sentence carries essential information with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not detail return values. It adequately covers input constraints, output ordering, and license requirement. It could optionally note error handling (e.g., invalid IP format), but the schema's pattern already handles validation hints. Overall, it is sufficiently complete for a simple lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description, format, and pattern for the 'ip' parameter. The description reiterates 'single IPv4 address' and mentions IPv6 rejection, but adds no new semantics beyond the schema. With full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'look up' and clearly defines the resource as 'Business Service Intelligence provider matches for a single IPv4 address'. It distinguishes from siblings like multi-ip-check (single vs. multiple IPs) and other bsi-*-stats tools (provider matches vs. aggregated stats).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool requires a BSI license, providing a key precondition. It implicitly suggests usage for single IPv4 lookups, and by naming 'single IPv4 address' it hints not to use for multiple IPs (use multi-ip-check) or for category/company/trust stats. However, it does not explicitly list alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and openWorld hints. The description adds the explicit time window constraint (1-7 days) and the performance overload warning, which goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one summarizing the tool's function and output dimensions, the other stating the crucial time window constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 optional params, no required) and the presence of an output schema, the description covers the key information: purpose, grouping dimensions, and important usage bound. Could benefit from noting that output is aggregate only, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 9 parameters. The description reinforces the days constraint and lists the output dimensions, providing context beyond the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it aggregates statistics for callback/C2 IPs, listing the exact breakdown dimensions (attack stage, file analysis, etc.), which distinguishes it from listing tools like list-callback-ips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for aggregate stats with a recent window, but does not explicitly compare to siblings like list-callback-ips or bsi-trust-stats. The warning against wide ranges provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint; description adds behavioral context: uses a cached list for lookups, case-insensitive slug matching. No contradictions. Provides useful details beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that conveys all essential information without redundancy or extraneous detail. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Description mentions caching, adding context for data freshness. Could include cache refresh timing but not necessary for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a basic description. Description adds meaning: exact match for id, case-insensitive match for slug, and the lookup is over a cached list, providing context beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get', the resource 'full record for a single GreyNoise tag', and the lookup method (by id or slug, case-insensitive, from cached list). It distinguishes from sibling tools like 'get-tag-activity' by specifying it retrieves the full record for a single tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage over a cached list but does not explicitly state when to use this tool versus alternatives (e.g., get-tag-activity). No guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true and openWorldHint=true. The description adds value by detailing that results are paginated and the use of a scroll token. It also lists available facets and query examples, giving the agent a clear understanding of the tool's behavior 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bullet-pointed facets, and examples. It is comprehensive but not overly verbose. All content is relevant and adds value. Minor room for tightening, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (query language, pagination, facets), the description covers all necessary aspects: what the tool does, how to use GNQL, available fields, example queries, and pagination. An output schema exists, so return values are documented separately. The description is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the three parameters (query, size, scroll). The description adds some context by explaining GNQL syntax and providing examples but does not significantly enhance parameter understanding beyond what the schema already provides. Baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search GreyNoise data using GNQL (GreyNoise Query Language). Returns full IP context results including raw scan data.' This distinguishes it from sibling tools like gnql-stats (aggregations) and gnql-timeseries (time series). The verb 'Search' with specific resource and output is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the GNQL language, provides examples, and notes pagination. However, it does not explicitly state when to use this tool vs. alternatives (e.g., gnql-stats for counts, gnql-metadata-query for metadata). The user can infer context from the examples, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. Description adds the nested bucketing behavior but does not disclose pagination, result format, or any side effects. Adequate but not rich beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with purpose. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description need not detail return values. Covers core behavior and constraints (time range, fields). Could mention optional filters, but schema covers that. Adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage). Description adds value by explaining that multiple fields produce nested buckets, which is not in schema. Justification for grouping behavior is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it aggregates session counts grouped by fields, with nested bucketing for multiple fields. This distinguishes it from siblings like session-timeseries or search-sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for aggregating counts by fields, but lacks explicit when-not-to-use or alternative tool references. Sibling tools exist but are not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by explaining the dynamic behavior based on the 'field' parameter. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and key distinction. Every word serves a purpose with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given schema coverage is 100% and an output schema exists, the description completes the picture by explaining the optional grouping behavior. Minor gap: does not detail the default sizing behavior when field is set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond schema by explaining the effect of the 'field' parameter on the output structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns session volume over time, with optional grouping by a field. This distinguishes it from sibling tools like gnql-timeseries which return different metric timeseries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly differentiates between use without field (single timeseries) and with field (per-group timeseries), giving clear context. However, it does not directly address when to use this tool versus siblings like gnql-timeseries or search-sessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the readOnlyHint and openWorldHint annotations by stating that the server produces a CSV and optionally includes per-value counts. It does not contradict annotations and provides useful output format information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the core function and output format in the first sentence and adds optional features and examples in the second. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema coverage and presence of an output schema, the description adequately covers the main use case. However, it could explicitly mention the scope parameter and provide more detail on the query usage to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with full descriptions, so the description does not add significant new meaning. While it reinforces the role of start/end_time and query, it does not explain nuances like scope or include_counts beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Return the distinct values'), the resource ('a single session field'), and constraints ('over a time range'). It also mentions optional per-value counts. This distinguishes it from sibling tools like search-sessions or session-fields, which return different results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete use cases ('extracting distinct IPs, ports, or other field values matching a query'), but does not explicitly state when not to use this tool or compare it to alternatives. The guidance is helpful but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool sends a test payload to verify delivery, which is consistent with the annotations (idempotentHint=true, destructiveHint=false). It adds context about verification without contradicting annotations. No additional behavioral details like auth or rate limits are provided, but annotations already cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that effectively communicates the tool's purpose. No filler or redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description adequately explains the purpose. An output schema exists (not shown), so return values are covered elsewhere. Minor gaps exist, such as what the test payload contains or how verification is reported, but overall it's sufficient for a test tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 4 parameters. The tool description does not add any additional meaning beyond the schema; it is a concise one-liner. With high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a test payload to a webhook URL to verify delivery before wiring it to an alert. The verb 'send test payload' and resource 'webhook URL' are specific, and the purpose is distinguished from sibling tools like create-alert which actually creates an alert.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'before wiring it to an alert', which implies the tool should be used to test webhook delivery prior to finalizing alert configuration. No explicit alternatives or exclusions are given, but the context is clear enough given the tool's specific purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the description does not need to reiterate safety. It adds value by detailing return fields (IPs, ports, timestamps, etc.), which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core action and list return fields, with no wasted words. Perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and annotations covering behavior, the description is complete. It specifies the single required input and typical output fields, fully sufficient for the tool's simple purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions 'by its ID' which aligns with session_id, but does not add any additional meaning beyond the schema's own descriptions. No extra value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves metadata and connection details for a single session by ID, listing specific fields returned. It distinguishes from sibling tools like 'search-sessions' which returns multiple sessions, and export tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a session ID and need full details, but does not explicitly mention when not to use or compare to alternatives like 'search-sessions' for listing. However, the context is clear enough for an agent to infer proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds beyond annotations by explaining the side effect of saving to a temporary directory and returning a file path, and suggests tools to open the file. No contradiction with annotations, which indicate non-read-only and open-world hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. The key action is front-loaded, and the file format and usage context are efficiently provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description correctly omits return value details. It covers the essential behavior: download, temporary storage, file path return, and compatibility with analysis tools. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal extra meaning for parameters. It does not elaborate on 'scope' or 'session_id' beyond what the schema already describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Download' and the resource 'raw PCAP capture for a single GreyNoise sensor session', which distinguishes it from sibling tools like 'export-sessions-pcap' that likely handle multiple sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (need a single session's PCAP) but does not explicitly state when not to use or list alternatives. The presence of sibling 'export-sessions-pcap' provides context but not direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint and openWorldHint, so the description adds value by detailing the two internal API calls and the resulting combined set with a 'source' field and total count. This goes 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the purpose, and each sentence adds essential information (what, no params, internal mechanics, output details). No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, readOnlyHint, openWorldHint, and an output schema (exists but not displayed), the description fully explains the tool's behavior: two calls, combined result with source field and total count. The agent has enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (100% coverage), and the description confirms it takes no parameters. Since there are zero parameters, a baseline of 4 is appropriate, and the description adds no extra meaning but is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists trending and anomalous GreyNoise vulnerability tags, specifies it takes no parameters, and explains the internal behavior of making two calls. It is distinct from sibling tools like 'get-tag-activity' which likely returns different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes no parameters are required, making usage straightforward, but does not explicitly compare with alternative tools or provide when/when-not guidance. It is adequate for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is lighter. It adds value by specifying that results are aggregated counts per time bucket, that the interval must be 'hour' or 'day', and that time bounds use ISO 8601 format. These details go 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences: the first states the core purpose, the second elaborates on output and use case, and the third gives parameter constraints. Every sentence adds value; no wasted words. It is front-loaded and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, output schema exists, annotations present), the description covers: purpose, use case, parameter constraints, and return value nature. It does not leave important gaps, and the output schema handles return details. The description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning: it reiterates that interval must be 'hour' or 'day' (already in schema as enum) and that time bounds use ISO 8601 (also in schema). This is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the number of unique IPs matching a GNQL query per hour/day over a time range', using a specific verb and resource. It distinguishes this tool from siblings like 'gnql-stats' and 'gnql-timeseries' by focusing on unique IP recall stats and trend analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states it is 'useful for trend analysis and understanding how scanning/attack activity changes over time', providing clear context for when to use it. However, it does not explicitly state when not to use it or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior. The description adds value by detailing parameter matching rules and the output summary structure. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first summarizes purpose and output, second details parameter behavior. It is concise, front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (though not shown), the description explains the summary output components and parameter behavior fully. Annotations provide open-world context. The description is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds detailed semantics: query matches across multiple fields, category and intention are exact case-insensitive, and days restricted to specific values with default. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (filter and aggregate), the resource (GreyNoise tags activity), and the output summary (total active IPs by classification, most active tags, per-tag detail). It distinguishes from sibling tools like get-tag-details and get-tag-activity by focusing on aggregation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidelines for parameter matching: query substring-matches name/description/slug/label, category and intention are exact case-insensitive, and days must be 1, 10, or 30. It does not explicitly state when to use this tool over alternatives, but the aggregation purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), the description discloses order preservation, whole-request failure on IPv6, and license requirement—no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first sentence states purpose and capacity, second covers order, failure mode, and prerequisites. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and full annotation coverage, the description still adds necessary constraints (IPv6 failure, license, order) and is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the 'ips' parameter (type, format, constraints). The description adds only behavioral context (order preservation) rather than clarifying parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (look up), resource (BSI provider matches), and constraints (up to 1,000 IPv4 addresses). It distinguishes this bulk tool from the likely single-IP sibling 'bsi-lookup'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: order preservation, IPv6 failure behavior, and license requirement. It does not directly name alternatives but the sibling list and task imply single vs bulk distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral context by specifying what is returned (field identifiers, types, groups, sortability). No contradictions or hidden side effects are present, and the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every word adds value. No redundancy or fluff; it efficiently conveys the tool's function and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, read-only, with an output schema), the description fully covers purpose, when to use, and what to expect. No gaps remain for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the 'scope' parameter described in the schema itself. The description does not repeat parameter details, which is acceptable. It adds no semantic value beyond the schema, earning the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to discover the queryable session field schema, including identifiers, types, groups, and sortability. It distinguishes itself from sibling tools that perform actual queries (e.g., search-sessions) by being a metadata discovery tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use the tool: 'Use these field names when building session queries, counts, connections, timeseries, and unique-value requests.' This provides clear guidance on its role as a prerequisite for constructing queries, leaving no ambiguity about context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and openWorld hints. The description adds value by detailing the output type (time-series IP counts and intention activity) and constraints on time range (days) and granularity (1h vs 24h). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. First sentence captures purpose and key constraint. Second sentence details parameter specifics. Well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters (all described), high schema coverage, and presence of an output schema, the description sufficiently covers what the tool does, required inputs, and behavioral nuances. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds critical usage semantics: the exclusivity constraint between 'id_or_slug' and 'cve', and the relationship between 'days' and 'granularity'. This goes beyond the schema's individual property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the specific resource 'time-series unique-IP counts and intention activity for a tag or by CVE'. It also highlights exclusivity of two parameters, distinguishing it from sibling tools like 'get-tag-details' or 'analyze-tags-activity'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Provide exactly one of id_or_slug or cve' and specifies allowed values for 'days' with default. However, it does not explicitly compare with alternatives or mention 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, and the description does not contradict these. It adds useful behavioral context: data refreshes hourly, and explains facet subtraction. No destructive behavior is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (facets, behavior, shortcuts, examples) and front-loaded with the purpose. However, it is lengthy; some introductory sentences about GNQL could be trimmed for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description covers query construction, facets, behavior, and examples thoroughly. It does not need to explain return values. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds significant context for the 'query' parameter by detailing GNQL syntax, facets, and examples, but for 'count' it only repeats schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Get aggregate statistics for results matching a GreyNoise GNQL query.' This clearly specifies the verb (Get), resource (aggregate statistics), and context (GNQL query), distinguishing it from siblings like gnql-metadata-query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Behavior' section noting how to subtract facets, data refresh frequency, and 'Shortcuts' with keywords like 'today' and 'interesting'. It provides many examples, giving strong usage guidance, though it lacks explicit contrast with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool provides vulnerability intelligence (read-only operation) and lists returned data categories (scores, stats, IP activity). No contradictions with annotations (readOnlyHint, openWorldHint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose, followed by specific details. No redundant words; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and presence of an output schema, the description fully covers what the tool does and how to invoke it. No additional details needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter. The description adds format validation and case-insensitivity guidance, enhancing understanding beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving GreyNoise vulnerability intelligence for a single CVE. It lists specific data points (CVSS/EPSS scores, KEV status, etc.) and distinguishes itself from sibling tools that handle sessions, IP lookups, or bulk operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the required format for cve_id ('CVE-YYYY-NNNNN') and notes case-insensitivity. It implies single-CVE usage but does not explicitly state when not to use it or mention alternatives, though sibling context makes the scope clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint. The description adds behavioral context: returns only metadata (no raw data), supports pagination via scroll token, and describes output formats including the structuredContent always being full JSON. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and differentiation, then logically expands on usage, pagination, and output formats. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, 100% schema coverage, output schema exists, and multiple siblings, the description covers all essential aspects: purpose, differentiation, query syntax support, pagination, quick mode, format options, and output behavior. It is complete for informed use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds significant meaning: explains 'quick' returns only IP and classification, details CSV columns, and notes that the text response differs from structuredContent. This goes well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Search') and resource ('GreyNoise data'), specifies the return type ('IP metadata without raw scan data'), and distinguishes from sibling gnql-query by noting it is 'lighter and faster'. This leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Use this when you need IP classification, tags, and metadata but not raw scan details.' It also compares to gnql-query and mentions pagination via scroll token, providing clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

[![greynoise-mcp-server MCP server](https://glama.ai/mcp/servers/GreyNoise-Intelligence/greynoise-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/GreyNoise-Intelligence/greynoise-mcp-server)

Score Badge

Copy to your README.md:

[![greynoise-mcp-server MCP server](https://glama.ai/mcp/servers/GreyNoise-Intelligence/greynoise-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/GreyNoise-Intelligence/greynoise-mcp-server)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/GreyNoise-Intelligence/greynoise-mcp-server'

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