Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rapid7-mcp search logs for failed login attempts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides AI assistants with access to Rapid7 InsightIDR, a cloud-native SIEM for modern detection and response. Query investigations, search logs with LEQL, analyze alerts, track assets, monitor user behavior, and manage threat intelligence.
Search and filter investigations by status, priority, assignee, date range
Create, update, and manage investigation lifecycle
Add comments and retrieve associated alerts
Build investigation timelines
Execute LEQL (Log Entry Query Language) queries across log sets
List available log sets (Firewall, DNS, DHCP, Endpoint, Cloud, Active Directory)
Retrieve individual log entries and aggregate statistics
LEQL syntax reference and examples
List and filter alerts by severity, type, status, date
Get full alert details with evidence and indicators
Update alert status (open, investigating, closed)
Evidence extraction for investigation
Search endpoints by hostname, IP, OS, agent status
Full asset details: software inventory, vulnerabilities, agent info
Recent activity: logins, processes, network connections
Search user accounts across the organization
Activity analysis: login patterns, locations, accessed assets
Risky user identification with behavior scoring
Anomaly detection and alert correlation
IOC management: IPs, domains, file hashes
Add indicators to threat library
Search for threat indicator matches across logs
List and manage saved LEQL queries
Create reusable queries with descriptions
LEQL syntax helper with examples
Related MCP server: rapid7-mcp-server
┌────────────────────────────────────────┐
│ MCP Client (LLM) │
└──────────────┬─────────────────────────┘
│ MCP Protocol (stdio)
┌──────────────▼─────────────────────────┐
│ rapid7-mcp server │
│ │
│ ┌──────────┐ ┌────────────────────┐ │
│ │ Prompts │ │ Resources │ │
│ │ 4 guides │ │ templates, LEQL, │ │
│ │ │ │ detection rules │ │
│ └──────────┘ └────────────────────┘ │
│ │
│ ┌──────────────────────────────────┐ │
│ │ Tools │ │
│ │ investigations │ logs │ alerts │ │
│ │ assets │ users │ threats│queries │ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ┌──────────────▼───────────────────┐ │
│ │ InsightIDR REST Client │ │
│ │ (client.ts + config.ts) │ │
│ └──────────────┬───────────────────┘ │
└──────────────────┼─────────────────────┘
│ HTTPS
┌──────────────────▼─────────────────────┐
│ Rapid7 InsightIDR Platform API │
│ https://<region>.api.insight.rapid7│
└────────────────────────────────────────┘git clone https://github.com/solomonneas/rapid7-mcp.git
cd rapid7-mcp
npm install
npm run buildSet environment variables:
export RAPID7_API_KEY="your-api-key"
export RAPID7_REGION="us" # us, eu, ca, au, ap
export RAPID7_ORG_ID="your-org-id" # optionalOr use a .env file:
RAPID7_API_KEY=your-api-key
RAPID7_REGION=us
RAPID7_ORG_ID=your-org-id{
"mcpServers": {
"rapid7": {
"command": "node",
"args": ["path/to/rapid7-mcp/dist/index.js"],
"env": {
"RAPID7_API_KEY": "your-api-key",
"RAPID7_REGION": "us"
}
}
}
}Add to your openclaw.json:
{
"mcp": {
"servers": {
"rapid7": {
"type": "stdio",
"command": "node",
"args": ["/path/to/rapid7-mcp/dist/index.js"],
"env": {
"RAPID7_API_KEY": "your-api-key",
"RAPID7_REGION": "us"
}
}
}
}
}Tool | Description |
| List/filter investigations by status, priority, assignee |
| Get full investigation details with timeline |
| Create new investigation |
| Update status, assignee, disposition |
| Add comment/note to investigation |
| Get alerts linked to an investigation |
| Execute LEQL queries against log sets |
| List available log sets |
| Get specific log entry by ID |
| Aggregate statistics for a time range |
| Get alerts with severity/type/status filters |
| Full alert details with evidence |
| Update alert status |
| Get evidence/indicators from an alert |
| Search endpoints by hostname, IP, OS |
| Full asset details with software/vulns |
| Recent activity for an asset |
| Search user accounts |
| User behavior analytics |
| Users with abnormal behavior scores |
| List IOCs in threat library |
| Add new IOC |
| Search for IOC matches in logs |
| List saved LEQL queries |
| Save a LEQL query for reuse |
| LEQL syntax reference and examples |
-- Find all blocked traffic from a source
where(source_address = 10.0.0.1 AND action = BLOCK)
-- Top talkers by connection count
groupby(source_address) calculate(count) sort(desc)
-- Failed logins for a specific user
where(user = "admin" AND result = FAILED_LOGIN)
-- HTTP errors by URL
where(status >= 400) groupby(url) calculate(count)
-- DNS queries to suspicious domains
where(query CONTAINS "malware") groupby(query) calculate(count)
-- Outbound connections on non-standard ports
where(destination_port != 80 AND destination_port != 443 AND direction = OUTBOUND)Prompt | Description |
| Guided alert investigation workflow |
| Search for IOC across all log sources |
| Analyze user activity for anomalies |
| Build chronological incident timeline |
URI | Description |
| Common investigation templates |
| LEQL syntax and examples |
| Built-in detection rule catalog |
npm run build # Compile TypeScript
npm run dev # Watch mode
npm run test # Run tests
npm run lint # Lint checkMIT
Add a comment or note to an InsightIDR investigation
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Comment text to add | |
| visibility | No | Comment visibility | PUBLIC |
| investigation_id | Yes | Investigation ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose behavioral traits such as that the comment is appended, whether it triggers notifications, or if the investigation must exist. The description is too minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb 'Add'. It is concise but could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description is insufficient. It does not explain return values, error conditions, or the effect of adding a comment on the investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema for parameters like body, visibility, and investigation_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and the resource ('comment or note to an InsightIDR investigation'). It is specific and uses a direct verb, but could be more precise (e.g., mention visibility parameter).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use, or how it relates to other tools like update_investigation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new IOC (IP, domain, hash, etc.) to the InsightIDR custom threat library
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| type | Yes | Type of indicator | |
| value | Yes | Indicator value (e.g., '10.0.0.1', 'malware.example.com', SHA256 hash) | |
| severity | No | Severity level of the threat | MEDIUM |
| confidence | No | Confidence score (0-100) | |
| description | No | Description of why this indicator is malicious | |
| threat_name | No | Associated threat name or campaign |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It only says 'Add a new IOC' but doesn't specify idempotency, duplicate handling, authorization needs, or side effects. Missing important context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded. However, it could include additional important details without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no output schema or annotations, the description is too sparse. It lacks information about return values, error handling, and behavioral constraints, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in the schema. The description adds minimal extra meaning beyond mentioning IOC types. Baseline is 3, and description does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a new IOC' with a specific verb and resource, and gives examples of IOC types (IP, domain, hash). It distinguishes from sibling tools like list_threat_indicators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus others. No mention of prerequisites, context, or when not to use it. The description just states the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new InsightIDR investigation with a title, priority, and status
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Investigation title | |
| status | No | Initial investigation status | OPEN |
| priority | No | Investigation priority | MEDIUM |
| disposition | No | Investigation disposition (typically set when closing) | |
| assignee_email | No | Email of the user to assign the investigation to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose behavior. It states the tool creates an investigation but omits potential side effects, permissions, or whether it returns the created object.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no extraneous words. Front-loaded with the action and key parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no output schema, the description is minimal. It does not mention return values or confirmation of creation, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter. The description adds no extra meaning beyond what's in the schema (e.g., 'title, priority, and status' are already described).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'InsightIDR investigation', and lists key attributes (title, priority, status). This distinguishes it from sibling tools like update_investigation and get_investigation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Usage is implied from the creation purpose, but no exclusion or when-not scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a LEQL query for reuse in InsightIDR
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the saved query | |
| description | No | Description of what this query does | |
| log_set_ids | Yes | Array of log set IDs this query applies to | |
| leql_statement | Yes | LEQL query statement to save |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only implies a write operation but does not mention side effects, required permissions, rate limits, or what happens on duplicate names. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the tool's core purpose without unnecessary words. It is well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, no output schema, and no annotations, the description is too brief. It does not explain return values, uniqueness constraints, error handling, or confirmation steps. The agent lacks critical information for safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions in the schema. The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Save'), the resource ('LEQL query'), and the context ('for reuse in InsightIDR'). It directly matches the tool name 'create_saved_query' and distinguishes it from sibling tools like 'list_saved_queries' and 'leql_help'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states what it does, leaving the agent without context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific InsightIDR alert including its detection rule and metadata
| Name | Required | Description | Default |
|---|---|---|---|
| alert_id | Yes | Alert ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavior. It implies a read-only operation but does not disclose auth requirements, rate limits, response format, or potential side effects. The description is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is reasonably complete. It identifies 'full details' and mentions specific content (detection rule, metadata). A slight improvement could clarify what 'metadata' encompasses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description reiterates the parameter's purpose ('Alert ID or RRN') without adding additional semantics or context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a specific InsightIDR alert, including detection rule and metadata. It distinguishes from siblings like get_alert_evidence (evidence only) and list_alerts (summaries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., get_alert_evidence for evidence, list_alerts for summaries). No usage conditions, prerequisites, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get evidence and indicators associated with an InsightIDR alert
| Name | Required | Description | Default |
|---|---|---|---|
| alert_id | Yes | Alert ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It only states a simple retrieval operation without mentioning any side effects, permissions, limits, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no extraneous words. It is front-loaded with the action and resource, but lacks additional detail that would be warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is sufficient but minimal. It does not explain the return format or any potential pagination, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so the baseline is 3. The description adds minimal value by specifying the context (InsightIDR alert) but otherwise repeats the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves evidence and indicators for an InsightIDR alert, using a specific verb and resource. It implicitly distinguishes from siblings like 'get_alert' but does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. There is no mention of prerequisites or 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.
Get full details of an InsightIDR asset including installed software, vulnerabilities, and network interfaces
| Name | Required | Description | Default |
|---|---|---|---|
| asset_id | Yes | Asset ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly implies a read operation by stating 'Get full details', but it does not explicitly confirm non-destructiveness, required permissions, or rate limits. The description is adequate but minimal for a simple retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It efficiently conveys the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter nature and lack of output schema, the description adequately covers what the tool does and what data it returns. It could mention whether the output is paginated or if any filters apply, but for a straightforward retrieval, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'asset_id' described as 'Asset ID or RRN'. The tool description does not add further semantics 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets full details of an InsightIDR asset, listing included data like software, vulnerabilities, and network interfaces. It distinguishes itself from sibling tools such as get_asset_activity and search_assets by specifying the exact resource and scope of details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing comprehensive asset details, but it lacks explicit guidance on when to use this tool versus alternatives like search_assets for listing or get_asset_activity for events. No exclusions or when-not-to-use advice is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent activity for an asset including logins, processes, and network connections
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of activity records to return (1-100) | |
| asset_id | Yes | Asset ID or RRN | |
| end_time | No | Filter activity before this ISO 8601 timestamp | |
| start_time | No | Filter activity after this ISO 8601 timestamp | |
| activity_type | No | Type of activity to retrieve | ALL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only mentions 'recent activity' without defining recency (e.g., default time range, sorting order). It fails to describe pagination, result limits, or behavior for multiple activity types. This lack of detail is a significant gap for a tool with 5 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence includes the verb, resource, and key included elements. No extraneous words; the description is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and moderate complexity, the description lacks critical information such as return format, ordering, time range defaults, and scope (single asset). It is too sparse to fully guide an agent that cannot infer from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains each parameter well. The description adds marginal value by grouping types (logins, processes, network connections) but does not enhance parameter understanding beyond schema defaults. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'asset activity', and explicitly lists included types (logins, processes, network connections). This distinguishes it from sibling tools like 'get_asset' (details) and 'search_assets' (search), making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing recent activity for a specific asset, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'search_asset_activity' or log-based tools). No exclusions or conditions are stated, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a specific InsightIDR investigation including its timeline
| Name | Required | Description | Default |
|---|---|---|---|
| investigation_id | Yes | Investigation ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description discloses the output (full details and timeline) but does not elaborate on permissions, side effects, or any behavioral nuances. Adequate but could be richer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, 13 words, front-loaded with verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description covers the purpose and output nature. Could be enhanced with more detail on return fields or limitations, but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described. The description adds 'including its timeline' but does not explain the ID format or return structure. Adds marginal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'full details of a specific InsightIDR investigation including its timeline'. It distinguishes from siblings like 'get_investigation_alerts' and 'search_investigations'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing details of a specific investigation, but lacks explicit guidance on when to use versus alternatives like 'search_investigations' or 'get_investigation_alerts'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all alerts associated with a specific investigation
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of alerts to return (1-100) | |
| index | No | Pagination index | |
| investigation_id | Yes | Investigation ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Get all alerts' but the input schema includes pagination parameters (size and index), indicating it may not return all at once. This contradiction is not addressed. No annotations are provided, so the description carries full burden but fails to disclose pagination behavior or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. Important details about pagination are missing. It is not front-loaded with critical information. Every word is earned, but the sentence is too terse for a tool with pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, pagination, no output schema), the description is incomplete. It does not explain the pagination behavior, return format, or how to interpret 'all alerts' in the context of size and index limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents each parameter. The description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate as description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and resource 'alerts' with the scope 'associated with a specific investigation'. It distinguishes well from siblings like get_alert (single alert) and list_alerts (all alerts potentially without investigation filter).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or when not to use it. Usage is implied by the name but not directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific log entry by its ID from a given log set
| Name | Required | Description | Default |
|---|---|---|---|
| log_id | Yes | ID of the specific log entry | |
| log_set_id | Yes | ID of the log set containing the entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the retrieval action, with no disclosure of side effects, permissions, rate limits, or error cases. For a read operation, a 2 is generous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks detail. It is front-loaded but could offer more structure without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval with 2 parameters and no output schema, the description is minimally adequate. However, it lacks information about return format, error handling, or expected behavior, so completeness is marginal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions are adequate. The description adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a specific log entry by ID from a log set. It uses specific verb+resource, and while it distinguishes from siblings like 'search_logs' by being ID-specific, it does not explicitly differentiate from 'get_alert' or similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, constraints, or when not to use it. The agent receives no context about selecting this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate statistics for a log set over a time range using a LEQL query
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time as Unix timestamp in milliseconds | |
| from | No | Start time as Unix timestamp in milliseconds | |
| query | No | LEQL query for aggregation (e.g., 'groupby(source_address) calculate(count)') | calculate(count) |
| log_set_id | Yes | ID of the log set | |
| time_range | No | Relative time range (e.g., 'Last 24 Hours', 'Last 7 Days') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It indicates a read operation ('Get') and mentions the LEQL query, but lacks details on error behavior, return format, or potential side effects. It is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words, conveying the essential information without any fluff. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality but lacks information about the return value (since no output schema is provided), error handling, or advanced usage tips. It is minimally sufficient for a tool with clear parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'aggregate statistics for a log set', and the method 'using a LEQL query'. It effectively distinguishes from sibling tools like get_log_entry (single log) and search_logs (raw logs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_logs or get_log_entry. There is no mention of prerequisites or 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.
Get users with abnormal behavior scores from InsightIDR's User Behavior Analytics (UBA)
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| index | No | Pagination index | |
| risk_level | No | Filter by risk level | |
| min_risk_score | No | Minimum risk score threshold (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates a read operation but does not mention permissions, rate limits, or whether results are paginated. It adequately states the purpose but lacks depth on side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core functionality without any wasted words or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate complexity (4 optional parameters, no output schema), the description is minimal. It does not explain return values or how to interpret 'abnormal behavior scores', leaving some gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains each parameter. The description adds no additional meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'users with abnormal behavior scores', and the source 'InsightIDR's User Behavior Analytics (UBA)'. It effectively distinguishes from sibling tools like search_users or get_user_activity by focusing on abnormal behavior scores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any preconditions, use cases, or situations where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get user behavior analytics data: login times, locations, accessed assets, and anomalies
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of activity records to return (1-100) | |
| user_id | Yes | User ID or RRN | |
| end_time | No | Filter activity before this ISO 8601 timestamp | |
| start_time | No | Filter activity after this ISO 8601 timestamp | |
| activity_type | No | Type of activity to retrieve | ALL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only lists data types but does not mention whether the tool is read-only, performance characteristics, pagination behavior, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct and to the point. No wasted words, but could be slightly more structured with a brief list for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 5 parameters and no output schema, the description lacks key details such as default time range, pagination behavior, and the nature of 'anomalies'. Users may need to infer behavior from the parameter names and types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. However, it could highlight the required user_id or explain the activity_type enum, but it does not. Baseline score of 3 per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves user behavior analytics data listing specific fields (login times, locations, accessed assets, anomalies). However, it does not differentiate from sibling tools like get_asset_activity or search_users that may also involve user activity data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_risky_users or search_users. No context about prerequisites or appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get LEQL (Log Entry Query Language) syntax reference, examples, and common patterns for InsightIDR log searches
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Specific LEQL topic to get help on | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the tool as returning reference material, which implies a read-only, non-destructive operation. No behavioral details beyond that are given, but it is not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with no unnecessary words, conveying the tool's purpose precisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple help tool with one enum parameter, the description sufficiently covers purpose and scope. No output schema is present, but the content type is implicit. Slight improvement could mention output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-documented enum parameter. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves LEQL syntax reference, examples, and common patterns, using specific verb 'Get' and resource 'LEQL syntax reference'. It distinguishes from sibling tools focused on investigations, alerts, and assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining LEQL help but does not explicitly state when to use this tool vs alternatives. However, the context is clear enough for an agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List InsightIDR alerts with optional filters for severity, type, status, and date range
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| sort | No | Sort field (e.g., '-created_time' for newest first) | |
| type | No | Filter by alert type/source | |
| index | No | Pagination index | |
| status | No | Filter by alert status | |
| end_time | No | Filter alerts created before this ISO 8601 timestamp | |
| severity | No | Filter by alert severity | |
| start_time | No | Filter alerts created after this ISO 8601 timestamp | |
| investigation_id | No | Filter alerts linked to a specific investigation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavior. It only states 'list alerts' with filters, but does not explain pagination (size, index), sorting ('-created_time'), rate limits, or return format. The lack of output schema makes this omission significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, highly concise and front-loaded with the action and resource. However, it could benefit from additional structure, such as a second sentence on pagination or sorting, to improve clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description provides insufficient context. It does not explain return values, pagination behavior, sort syntax, or how filters combine. It lacks details needed to use the tool effectively, especially without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions. The tool description adds minimal value by naming filter categories (severity, type, status, date range) that are already detailed in the schema. It does not explain parameter interactions or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and resource 'InsightIDR alerts', and mentions optional filters. It distinguishes from sibling tools like 'get_alert' (single alert) and 'search_investigations' (different entity). However, it does not mention all filter parameters (e.g., investigation_id, size, sort).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_alert' or 'search_investigations'. There is no mention of prerequisites, use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available log sets in InsightIDR (Firewall, DNS, DHCP, Endpoint, Cloud, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies a safe read-only operation, but lacks details on potential pagination, performance impact, or authentication requirements. Adequate for a simple list with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with verb first, lists examples efficiently. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and a simple listing operation, the description fully informs the agent about what the tool does and provides examples of log sets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. No need for parameter explanation, baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List' and resource 'all available log sets' with concrete examples (Firewall, DNS, DHCP, Endpoint, Cloud), distinguishing it from sibling tools like 'list_alerts' or 'list_saved_queries'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives, such as when a specific log set is needed or how to filter. No context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved LEQL queries available in InsightIDR
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| index | No | Pagination index | |
| search | No | Search saved queries by name or description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but fails to disclose that the operation is read-only, or any pagination behavior beyond what the schema hints at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise and front-loaded with the verb. However, it is so brief that it lacks structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should explain the return format or pagination. It does not, leaving the agent with incomplete context for a list endpoint with optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning to the parameters; it only restates the resource.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource 'saved LEQL queries' and the product 'InsightIDR', distinguishing it from sibling tools like create_saved_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as search_logs or create_saved_query. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List IOCs (IPs, domains, hashes) in the InsightIDR threat library
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| type | No | Filter by indicator type | |
| index | No | Pagination index | |
| search | No | Search across indicator values and descriptions | |
| source | No | Filter by indicator source (e.g., 'rapid7', 'custom', 'misp') | |
| threat_name | No | Filter by associated threat name or campaign |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states 'List IOCs,' implying a read operation, but does not explain pagination behavior, rate limits, or whether the response includes metadata like total count. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks sufficient detail. It is not wasteful, but it misses opportunities to add value, such as explaining output format or pagination. Merely adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain the return format (e.g., list of objects with fields like value, type, source). It does not mention pagination behavior even though the schema includes index and size parameters. The description is incomplete for a paginated list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. The description adds no additional meaning beyond the schema; it only mentions 'IPs, domains, hashes' which is a subset of the available types. Baseline 3 is appropriate as the schema already documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists IOCs (IPs, domains, hashes) in the InsightIDR threat library, specifying the resource and action. However, it does not differentiate from siblings like search_threat_activity or add_threat_indicator, missing a chance to clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. No mention of prerequisites, use cases, or situations where another tool would be better, leaving the agent without decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search InsightIDR assets (endpoints) by hostname, IP address, OS, or agent status
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| index | No | Pagination index | |
| domain | No | Filter by Active Directory domain | |
| search | No | General search term across asset fields | |
| os_type | No | Filter by OS type (e.g., 'Windows', 'Linux', 'macOS') | |
| hostname | No | Filter by hostname (partial match supported) | |
| ip_address | No | Filter by IP address | |
| agent_status | No | Filter by agent status (e.g., 'ACTIVE', 'INACTIVE', 'STALE') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. The description only lists search fields and omits behavioral traits such as pagination behavior, rate limits, error handling, or return format. It does not disclose any side effects or system constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the action and resource with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 optional parameters and no output schema, the description should explain pagination, default behavior, or result structure. It lacks these details, making it insufficient for an agent to fully understand invocation requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions in the schema itself. The tool description adds minimal value beyond listing a few fields; it does not clarify edge cases, format expectations, or interaction between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('InsightIDR assets (endpoints)') and specific search criteria (hostname, IP address, OS, agent status). It distinguishes the tool from sibling tools like search_investigations or search_users, which cover different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching assets by common fields but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and filter InsightIDR investigations by status, priority, assignee, or date range
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| sort | No | Sort field (e.g., 'created_time' or '-created_time' for descending) | |
| index | No | Pagination index | |
| status | No | Filter by investigation status | |
| end_time | No | Filter investigations created before this ISO 8601 timestamp | |
| priority | No | Filter by priority level | |
| start_time | No | Filter investigations created after this ISO 8601 timestamp | |
| assignee_email | No | Filter by assignee email address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It mentions listing/filtering but does not state read-only nature, side effects, rate limits, or pagination behavior. As a search tool, it is likely read-only, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 15 words with no redundancy. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description is adequate but incomplete. It lists filter categories but omits mention of pagination (index/size) or sorting behavior, which are important for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are well-documented in the schema. The description adds a high-level summary of filter categories but does not provide additional semantics beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List and filter' and the resource 'InsightIDR investigations', and specifies filtering dimensions (status, priority, assignee, date range). This distinguishes it from sibling tools like get_investigation (single resource) and list_alerts (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing/filtering investigations but does not provide explicit guidance on when to use or avoid this tool versus alternatives such as get_investigation or search_assets. No exclusion criteria are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a LEQL (Log Entry Query Language) query against a specific log set in InsightIDR
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End time as Unix timestamp in milliseconds | |
| from | No | Start time as Unix timestamp in milliseconds | |
| query | Yes | LEQL query statement (e.g., 'where(source_address = 10.0.0.1)', 'where(action = BLOCK) groupby(source_address) calculate(count)') | |
| per_page | No | Number of log entries per page (1-500) | |
| log_set_id | Yes | ID of the log set to search. Use list_log_sets to find available log sets. | |
| time_range | No | Relative time range (e.g., 'Last 1 Hour', 'Last 24 Hours', 'Last 7 Days'). Used when from/to are not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention pagination, rate limits, return format, or side effects, leaving significant gaps for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. However, it could be slightly expanded for clarity without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no output schema, and no annotations, the description is insufficient. It lacks details on pagination, time range usage, query syntax examples, and expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what is in the schema; it briefly mentions LEQL and log set but does not elaborate on parameter nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes a LEQL query against a specific log set in InsightIDR, which is specific and distinguishes from sibling tools like get_log_entry (single entry) and get_log_stats (statistics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get_log_entry or leql_help. The description lacks context on prerequisites or 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.
Search for threat indicator matches in InsightIDR logs — find where known IOCs have been seen
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Number of results to return (1-100) | |
| index | No | Pagination index | |
| end_time | No | Filter matches before this ISO 8601 timestamp | |
| start_time | No | Filter matches after this ISO 8601 timestamp | |
| indicator_type | No | Filter by indicator type | |
| indicator_value | No | Specific indicator value to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether the operation is read-only, requires specific permissions, or has side effects. The description merely states 'search' without confirming safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear, front-loaded purpose. No extraneous words; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema, the description does not explain return format, pagination behavior, or how filters combine. Schema covers parameter details but tool description lacks guidance on usage patterns and response expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, describing all 6 parameters with meaningful descriptions. The tool description adds no additional meaning beyond the schema, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('Search'), resource ('threat indicator matches in InsightIDR logs'), and purpose ('find where known IOCs have been seen'), distinguishing it from sibling search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., search_logs, search_assets). The description implies usage for IOC matching but lacks exclusions or context-specific recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search user accounts monitored by InsightIDR by name, email, domain, or department
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter by user display name (partial match) | |
| size | No | Number of results to return (1-100) | |
| No | Filter by email address | ||
| index | No | Pagination index | |
| domain | No | Filter by Active Directory domain | |
| search | No | General search across user fields | |
| disabled | No | Filter by account disabled status | |
| department | No | Filter by department |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description alone must disclose behavioral traits. It only mentions the search capabilities and fields, without covering pagination, response structure, or any side effects. The schema already covers parameters; no new behavioral context is added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, 8 parameters, and no annotations, the description is insufficient. It does not clarify pagination, result format, or the fact that it is a read operation. Richer context is needed for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters described in schema). The description mentions only a subset of parameters (name, email, domain, department) but does not add meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches user accounts monitored by InsightIDR using specific fields (name, email, domain, department). It distinguishes from sibling tools like search_assets or search_investigations by focusing on users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching users by the listed fields but does not explicitly state when to use this tool versus alternatives (e.g., search_assets, search_investigations). No direct comparison or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of an InsightIDR alert (open, investigating, or closed)
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | New alert status | |
| alert_id | Yes | Alert ID or RRN | |
| assignee_email | No | Email of the user to assign to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It correctly identifies the tool as a mutation ('Update'), but it does not mention any side effects, authorization requirements, rate limits, or whether changes are reversible. For a simple status update, this is minimally acceptable but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys all necessary information without any superfluous words or repetition. It is front-loaded with the action and resource, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (updating a status with three well-defined parameters, all documented in the schema, and no output schema needed), the description is complete. It covers the what and the allowed values, which is sufficient for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions in the schema). The tool's description does not add any additional meaning beyond what the schema already provides. For example, it does not explain the relationship between assignee_email and status changes. Hence, the description adds no extra value over the schema, fitting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the specific resource ('status of an InsightIDR alert'), and enumerates the allowed status values ('open, investigating, or closed'). This provides a precise verb+resource combination that distinguishes it from sibling tools like get_alert or list_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool is used to update alert status. While it does not explicitly mention when not to use it or suggest alternatives, the context is unambiguous given the tool's name and the sibling tools (e.g., update_investigation applies to a different resource). No exclusions are stated, but the purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing investigation's status, priority, assignee, or disposition
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New investigation title | |
| status | No | New investigation status | |
| priority | No | New investigation priority | |
| disposition | No | Investigation disposition | |
| assignee_email | No | Email of the new assignee | |
| investigation_id | Yes | Investigation ID or RRN |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It says 'Update' indicating mutation but lacks details on permissions, partial updates, side effects, or return value (no output schema). Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 10 words, efficient and front-loaded with action and resource. However, it omits the 'title' field, which is a minor omission. Overall well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is insufficient. It fails to explain partial update behavior, required parameters (investigation_id is required but not highlighted), or response format, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds no extra meaning beyond listing fields; it does not explain parameter constraints, relationships, or formatting beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it updates an investigation and lists four specific updatable fields (status, priority, assignee, disposition). However, it omits the 'title' field from the schema, making it slightly incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like create_investigation or search_investigations. The phrase 'Update an existing investigation' implies context, but no when-not or sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_investigation_commentadd_threat_indicatorcreate_investigationcreate_saved_queryget_alertget_alert_evidenceget_assetget_asset_activityget_investigationget_investigation_alertsget_log_entryget_log_statsget_risky_usersget_user_activityleql_helplist_alertslist_log_setslist_saved_querieslist_threat_indicatorssearch_assetssearch_investigationssearch_logssearch_threat_activitysearch_usersupdate_alert_statusupdate_investigationScored across 26 tools
Each tool targets a distinct resource and action, such as creating vs listing investigations or getting alert details vs listing alerts. The descriptions clearly differentiate between similar-sounding tools, ensuring no ambiguity.
All tool names follow a consistent verb_noun pattern with underscores (e.g., create_investigation, list_alerts, get_asset). The verbs are appropriately chosen for the operation, and the naming is uniform throughout.
With 26 tools, the count is slightly above the recommended range for a well-scoped server, but each tool serves a distinct purpose in the InsightIDR domain, covering investigations, alerts, assets, logs, and threat intelligence. No tools seem redundant.
The tool set covers CRUD-like operations for key entities (investigations, alerts, threats) and includes search and query capabilities. Minor gaps exist, such as the absence of delete tools for investigations or threat indicators, but core workflows are well-supported.
SOAR security playbooks for AI agents: fetch, full-text search, and count. Metered via Stripe.
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Search log events, investigate anomalies, and manage cases in your Knowledge Grid tenant.
Manage incident alerts, events, and workflows with custom automations
