magicsword-mcp

Official

by magicsword-io

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Investigate MagicSword audit/block events

list_events

Read-onlyIdempotent

Searches normalized Investigate events across name, filename, path, hash, publisher, computer, and package family, with optional type, status, policy, and endpoint filters.

Instructions

Searches normalized Investigate events across name, filename, path, hash, publisher, computer, and package family, with optional type, status, policy, and endpoint filters. For “show filename audit events for image.png”, use type=filename, status=audited, file_name=image.png. Defaults to audited and blocked events over the last 24 hours, based on when they were last observed. Returns file paths, publishers, hashes, endpoint names, occurrence counts, timestamps, and rule context without raw telemetry. Search is read-only. To create rules, review the results and pass selected event IDs to manage_policy_rules with an explicit status and optional rule type. Requires alerts:read.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_events"
  }
}

Input Schema

Name	Required	Description
`q`	No	Case-insensitive literal substring search across name, filename, path, hash, publisher, computer, and package family. Up to 120 characters, including Unicode and punctuation; %, _, and * are literal. Omit type to search across event types. Combine with file_name for an exact filename.
`type`	No	Comma-separated event types, e.g. process,filepath,hash
`hours`	No	Lookback window in hours; defaults to 24
`limit`	No
`since`	No	ISO timestamp lower bound; overrides hours when provided
`offset`	No
`status`	No	Comma-separated statuses, e.g. audited,blocked
`platform`	No
`file_name`	No	Exact, case-sensitive filename, e.g. image.png; punctuation is literal
`policy_id`	No
`endpoint_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.1.3Oct 22, 2026

addedInput schema / properties / file_name

Added value: +{
+  "description": "Exact, case-sensitive filename, e.g. image.png; punctuation is literal",
+  "maxLength": 255,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / offset / maximum

Previous value: -9007199254740991New value: +1000000

changedInput schema / properties / q / description

Previous value: -"Search name, file, hash, path, or computer"New value: +"Case-insensitive literal substring search across name, filename, path, hash, publisher, computer, and package family. Up to 120 characters, including Unicode and punctuation; %, _, and * are literal. Omit type to search across event types. Combine with file_name for an exact filename."

changedInput schema / properties / q / maxLength
```
Previous value: -255New value: +120
```

addedInput schema / properties / q / pattern

Added value: +"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"

First observedv0.1.1Oct 15, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the default scope is audited+blocked events over 24 hours keyed on last-observed time, that raw telemetry is excluded, and that alerts:read is required. That default-window behavior is exactly the kind of trait an agent cannot infer from the schema.

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

Conciseness4/5

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

Front-loaded with purpose and filters, then a concrete example, then defaults, then the rule-creation handoff. Sentences are dense but each carries non-redundant information; only the returned-fields list is slightly over-packed.

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 an 11-parameter, no-output-schema search tool the description does the needed work: it names what comes back (paths, publishers, hashes, endpoint names, counts, timestamps, rule context) and covers safety and auth. Gaps are limited to pagination semantics and the platform/policy_id/endpoint_id filters, which are UUID/enum-constrained and largely self-explanatory.

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

Parameters4/5

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

With 55% schema coverage, roughly half the parameters (limit, offset, platform, policy_id, endpoint_id) have no structured description. The narrative compensates for the important ones by explaining the q-vs-file_name relationship ('combine with file_name for an exact filename'), the type/status value examples, and the presence of policy/endpoint filters — but it never characterizes the pagination or platform 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 opens with a specific verb and resource — 'Searches normalized Investigate events' — and enumerates the searchable fields (name, filename, path, hash, publisher, computer, package family) plus the filter axes. It clearly distinguishes a read-only event search from rule mutation (manage_policy_rules) and alert triage.

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?

It provides a concrete worked example ('show filename audit events for image.png' → type=filename, status=audited, file_name=image.png) and states the default window/filters, which tells an agent when defaults are appropriate. It also routes rule creation to manage_policy_rules with an explicit handoff. It does not contrast itself with the sibling find_alerts, leaving that one comparison to inference.

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