Enables web search through the Brave Search API as an optional search provider, returning results with source URLs and timestamps.
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., "@221B inspect https://example.org and summarize the page"
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 local MCP server for OSINT research. Give your AI client tools to find public profiles, search the web, inspect pages, and export findings with sources and timestamps. No API keys required by default.
Requires Git and Python 3.11+.
On macOS or Linux:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install '.[sherlock]'
221b-mcp doctorOn Windows:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[sherlock]"
.\.venv\Scripts\221b-mcp.exe doctorThe sherlock extra enables username searches. Skip it with pip install . if you only
need the other tools.
Add a stdio server to your MCP client. For clients using mcpServers JSON:
{
"mcpServers": {
"221b": {
"command": "/absolute/path/to/221B-MCP/.venv/bin/221b-mcp",
"args": ["serve"]
}
}
}Replace the path with your installation. Your client starts the server; there is no web UI or HTTP endpoint. Try asking: “Use 221B to inspect https://example.org.”
Related MCP server: wrg-mcp-server
Tool | What it does |
| Keyless metasearch through DDGS, or optional Brave API search |
| Find candidate accounts using locally installed Sherlock |
| Extract text, links, and email addresses from public HTML/text pages |
| Look up DNS records and available RDAP registration data |
| Retrieve recorded services for a public IP using an optional Shodan key |
| Search Shodan's indexed services using native query filters |
| Find Wayback captures of an exact URL |
| Export saved evidence IDs as JSON or Markdown |
Username searches accept depth: light (default, 20 curated sites), dev
(developer platforms), or complete (all available Sherlock sites, including adult
sites, with upstream exclusions). An explicit sites list overrides the preset.
Allow a client tool timeout above 600 seconds for complete scans.
Results include source URLs, retrieval timestamps, and status information. Username matches do not prove identity. Coverage varies, sites can block requests, and page inspection does not render JavaScript.
Run 221b-mcp init to select Brave and save its key in macOS Keychain, Windows
Credential Manager, or Linux Secret Service. Linux needs an available Secret Service
session. Setup fails if the OS store cannot save and read back the key.
For containers, set BRAVE_API_KEY_FILE to a mounted UTF-8 file containing the key.
Credential precedence is secret file → BRAVE_API_KEY environment → OS store.
Choose provider="brave" on a call, or set MCP_221B_SEARCH_PROVIDER=brave; a key alone does not switch providers.
Run 221b-mcp init and choose to configure Shodan, or supply SHODAN_API_KEY_FILE
or SHODAN_API_KEY. Precedence is secret file → environment → OS store, using
a separate credential from Brave. Shodan is optional and independent of the web-search
provider. doctor reports local credential status without making an API call or checking
your subscription. Restart your MCP client after installing the updated server.
Examples of tool arguments:
lookup_shodan_host(ip="8.8.8.8")
search_shodan(query='org:"Example" port:443', limit=10, page=1)Host lookup returns general host information and up to 100 recorded services. Search
returns service observations, so an IP can appear more than once for different services.
limit accepts 1–100 (default 10); page starts at 1. Each search fetches exactly one
Shodan page of up to 100 services and then applies the output limit. A smaller limit does
not reduce API credit usage. Results report the total matches and any omitted page results.
Search requires suitable account access and can consume query credits, including for filtered queries and later pages; see the Shodan API documentation. There is no automatic pagination or retry. Both tools read existing Shodan observations; they do not initiate scans. Observation timestamps are separate from retrieval timestamps, and recorded ports do not establish current reachability. Banner excerpts are limited to 2,000 characters with truncation indicated. Responses retain the shared 2 MB HTTP limit.
221b-mcp doctor shows configuration, evidence, and log paths. OS-store presence is
reported from setup metadata, without unlocking or verifying the store. Override them with
MCP_221B_CONFIG, MCP_221B_DATA_DIR, and MCP_221B_LOG_DIR. Evidence is kept until
manually removed. Operational logs omit query contents and keys; external sources still
receive requests, and results are returned to your AI client.
With Docker running, build and check the image:
docker build -t 221b-mcp .
docker run --rm 221b-mcp doctorFor an MCP client, use docker as the command with these arguments:
run --rm -i -v 221b-data:/data 221b-mcpUse -i without -t. The container runs as a non-root user; the named volume preserves
evidence and logs. Rebuild the image after code changes.
For Brave, mount a secret read-only and pass its path (never bake it into the image):
docker run --rm -i -v 221b-data:/data \
--mount type=bind,src=/absolute/path/brave-key,dst=/run/secrets/brave,readonly \
-e BRAVE_API_KEY_FILE=/run/secrets/brave \
-e MCP_221B_SEARCH_PROVIDER=brave 221b-mcpThe file must be readable by container UID 10001. Mounted files are not encrypted by
221B; protect the host file or use your deployment's secret manager. secrets/ is excluded
from Git and Docker builds. Host OS credentials are not automatically shared with containers.
For Shodan, use the same mounted-secret pattern:
docker run --rm -i -v 221b-data:/data \
--mount type=bind,src=/absolute/path/shodan-key,dst=/run/secrets/shodan,readonly \
-e SHODAN_API_KEY_FILE=/run/secrets/shodan 221b-mcppython -m pip install -e '.[dev,sherlock]'
ruff check .
ruff format --check .
pytest -qserver.py owns the lifecycle, tools.py defines the public tools, and
tool_handlers/ holds their implementations. runtime.py connects handlers to shared
services. Tests cover handlers and a real local MCP handshake without live web requests.
MIT. See LICENSE.
Export 1–100 existing evidence record IDs to a new local JSON or Markdown file.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | json | |
| record_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It usefully notes the 1–100 count limit, that records must already exist, and that a new local file is created. It does not disclose file naming, default export directory, behavior for invalid/missing IDs, or return values.
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, tightly worded sentence that front-loads the core behavior and output format. Every element earns its place with no wasted phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with two parameters and no output schema, the description covers the essential inputs and output format. It omits minor operational details like destination path and return behavior, but these are not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to both parameters: record_ids are evidence record IDs, and format maps to JSON or Markdown. It even adds the 1–100 count constraint, which the schema does not express.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (export), a specific resource (existing evidence record IDs), a range (1–100), and the output types (local JSON or Markdown file). It clearly differentiates from the sibling search/lookup tools, which are investigation-oriented rather than export-oriented.
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 the tool is for exporting evidence records to local files, while siblings are search/lookup tools. However, there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public HTML/text page and extract text, links and emails. No browser rendering.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does disclose a key trait: 'No browser rendering' means JavaScript rendered pages will not work. It also clarifies the page must be public and that extraction yields text, links, and emails, which is meaningful behavioral context beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences contain the full operational contract: fetch, extract type, URL class, and rendering limitation. Nothing is wasted and every clause contributes to selection or correct invocation.
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 one-parameter tool with no output schema, the description covers what the tool does, what it can be called on, and its core limitation. Minor omissions such as failure behavior on non-HTML URLs or rate limit handling, but these are not critical given the exposed simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It does: the 'url' parameter has to target a public HTML/text page, not a private, binary, or non-HTML resource. It doesn't spell out URL formatting, but for a single parameter it supplies enough extra semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: fetch a public HTML/text page and extract text, links, and emails. It clearly distinguishes itself from search and lookup siblings by saying it retrieves a specific page directly rather than searching or resolving domains.
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: use it when you have a direct public HTML/text URL and want extracted content. However, it does not explicitly say when not to use it, nor does it name alternatives like search_web for discovery or lookup_domain for domain intelligence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up A, AAAA, MX, NS and TXT DNS records, plus available RDAP registration data.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. 'Look up' and the caveat 'available RDAP registration data' convey a read-oriented query and hint that RDAP data may be absent, but the description does not disclose failure modes, data source, rate limits, or return 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?
One sentence, front-loaded verb, and no filler; every phrase contributes either the record types or the RDAP caveat. This is an efficient, scannable definition.
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 one simple parameter and no output schema, the description is adequate for basic tool selection, but it omits what the returned DNS/RDAP data looks like and any error or availability edge cases. An agent can invoke it, but cannot fully predict output variability.
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 provides only a `domain` string with 0% description coverage. The description repeats that the tool operates on domain names but never specifies the expected format (e.g., bare domain, no protocol, no trailing slash) or whether IDNs/punycode are accepted, so it adds little meaning beyond the parameter name.
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 names a concrete verb ('Look up') and specific resources (A/AAAA/MX/NS/TXT records and RDAP data), so the tool's domain scope is clear. The explicit record-type list also differentiates it from sibling lookup tools like lookup_shodan_host, which focus on Shodan 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?
The record types give an implied use case: call this when DNS or RDAP registration data is needed for a domain. It does not explicitly state when not to use it or name alternatives such as lookup_shodan_host or search_web, so routing guidance is left mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve Shodan's recorded services for a public IP. Requires a Shodan API key.
Returns up to 100 services and bounded banner excerpts. Observations are not live checks.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the full burden of disclosure, and it delivers: it states the API-key auth requirement, the 100-result cap, the bounded/truncated banner behavior, and the critical caveat that observations are not live checks. This goes well beyond what a bare description would offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the purpose is front-loaded, the prerequisite second, and the behavioral limits third. There is no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and no annotations, the description covers the purpose, auth, result cap, truncation, and data freshness — enough for correct invocation. Minor missing items (rate limits, error behavior without a key, explicit sibling routing) are each non-blocking, so the overall profile remains strong.
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?
With 0% schema description coverage, the plain string 'ip' needs the description to clarify acceptable values, and 'a public IP' does add meaningful scope. However, it leaves open address family (IPv4 vs IPv6), casing/format expectations, and rejects like CIDR or private ranges, so the compensation is partial.
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 names a specific verb and resource ('Retrieve Shodan's recorded services') with a clear target ('for a host IP'), which distinguishes it from sibling tools like search_shodan or lookup_domain. It also sharpens the definition by bounding the result set (up to 100 services) and clarifying the data is recorded, not live.
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 a single context: use it when you have a public IP and want Shodan's historical observations; the API-key requirement is a prerequisite. It never explicitly names when-not-to-use or routes to siblings such as search_shodan or lookup_domain for other IP/domain tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Wayback captures of an exact URL, deduplicated by digest. At most 100 captures.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does usefully disclose two traits: results are deduplicated by digest and the total is capped at 100 captures. However, it does not describe the return format, what fields a capture includes, or any error behavior, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. Every element ('exact URL', 'deduplicated by digest', 'at most 100 captures') conveys necessary information in minimal space, and the key action is 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?
For a simple read-only search tool, the description covers the core function, a key behavioral trait (dedup), and a numeric cap. It lacks an output schema and does not spell out return fields, and the limit parameter semantics are not fully explicit, but the overall complexity is low enough that the tool can be invoked correctly with the information provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions for either parameter, so the description must compensate. It clarifies that url must be an exact URL and implies an upper bound on results, but it never explicitly defines the limit parameter's meaning or its relationship to the default of 20, leaving partial ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Find') on a specific resource ('Wayback captures') with a clear constraint ('exact URL') and an explicit deduplication behavior. This clearly differentiates the tool from siblings like search_web, inspect_page, and lookup_domain, which target other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that the tool is for archived captures of a specific URL, implying use when historical snapshots are needed rather than live web results. It does not explicitly name alternatives or exclusions, but the 'exact URL' qualifier and Wayback focus make the selection context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Shodan's indexed services using native filters. Requires a Shodan API key.
May consume query credits. Fetches one explicit page of up to 100 services; limit (1–100) caps returned evidence, not credit usage. No automatic pagination or retries.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses credit consumption, explicit pagination (one page, up to 100 services), the semantics of the limit parameter (caps evidence, not credits), and the lack of automatic pagination/retries. This is thorough 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?
The description is concise, with the core purpose front-loaded in the first sentence and behavioral details in a separate paragraph. No redundant or filler content exists; every sentence adds value.
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 adequately covers purpose, behavior, and key parameter semantics, which is sufficient for a search tool lacking annotations and output schema. Minor gaps include exact query syntax and response format, but these are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning to 'limit' (caps returned evidence, not credits) and implies 'page' via 'one explicit page'. However, the 'query' parameter is only referenced as 'native filters', leaving syntax to the user's knowledge. This is partial compensation.
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 'Search', the resource 'Shodan's indexed services', and the method 'using native filters'. This distinguishes it from siblings like search_web or search_username by specifying the Shodan platform.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool (searching Shodan with native filters) but does not explicitly mention alternatives or when not to use it. Given siblings like lookup_shodan_host, a brief differentiator would help, but the description's specificity suffices for basic routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find candidate accounts with local Sherlock.
depth: light (default) checks 20 curated popular sites; dev checks developer platforms; complete requests all available sites, including adult sites, with a 10-minute deadline. Upstream false-positive exclusions apply. Explicit sites override the preset's selection. Requires the sherlock package extra. A match does not establish the owner's identity.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | light | |
| sites | No | ||
| username | Yes |
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 thoroughly discloses depth modes (light/dev/complete with specific site counts and a 10-minute deadline for complete), inclusion of adult sites, upstream false-positive exclusions, explicit site override behavior, a prerequisite (sherlock package extra), and a critical caveat that a match does not establish identity. This is far beyond minimal disclosure and gives the agent a clear expectation of side effects and limitations.
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 concise yet dense, with every sentence contributing value. It front-loads the core purpose, then efficiently lists depth modes, caveats, and requirements. No filler or redundancy; each clause earns its place. The structure is clear and scannable.
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 no annotations and no output schema, the description covers all essential operational details: depth modes, time limits, site selection behavior, prerequisites, and a key limitation. It does not describe the exact return format, but 'candidate accounts' implies the output is a list of accounts, which is sufficient for an agent to invoke the tool correctly. The description is complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully explains the 'depth' parameter (enum meanings), and indirectly explains 'sites' via 'Explicit sites override the preset's selection'. The 'username' parameter is self-explanatory from the tool's purpose. While the description does not formally name each parameter, it adds substantial meaning beyond the schema's bare types and enums.
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 a specific action ('Find candidate accounts') on a specific resource (username) using a specific method ('local Sherlock'). This distinguishes it from sibling tools like search_web (general web search) and search_shodan (host lookup). The purpose is unambiguous and cannot be confused with other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the tool is for username-based account discovery, and details depth options and site overrides. However, it does not explicitly state when to choose this tool over alternatives like search_web or search_archives, nor does it provide when-not-to-use guidance. The context is clear enough to imply usage, but explicit exclusions or alternative routing are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find public mentions; defaults to keyless metasearch. Max 20 results.
Supports search operators where the selected engines support them. Optional provider='brave' uses the Brave API and requires a key. Omit provider to use the configured default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| provider | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It usefully states the default keyless mode, the 20-result cap, Brave API key requirement, and operator support variability. However, it does not disclose output format, pagination, rate limits, or error behavior, leaving notable gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the core purpose and then provide essential constraints and provider options. There is no filler or redundant restating of schema fields.
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 tool is simple and the description covers the essential call parameters: query, limit, provider, and max results. However, with no output schema and no annotations, the description should say more about what the returned results look like and any operational constraints (e.g., rate limits or engine coverage) for an agent to fully rely on it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description carries the parameter burden. It explains provider semantics and key requirements, and 'Max 20 results' adds meaning to the limit parameter. Query is left to inference and the limit parameter's exact role is not explicitly mapped, so compensation is only partial.
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 and resource ('Find public mentions') and clearly identifies the default behavior as keyless metasearch. It does not explicitly distinguish from sibling search tools like search_username or search_archives, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives provider-level guidance ('Omit provider to use the configured default') and notes Brave's key requirement, but it provides no guidance on when to choose this tool over sibling tools such as search_archives or search_shodan. There is no explicit when-to-use or when-not-to-use guidance for the tool itself.
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.
v0.1.0export_findingsinspect_pagelookup_domainlookup_shodan_hostsearch_archivessearch_shodansearch_usernamesearch_webScored across 8 tools
Each tool targets a distinct resource and action: username search, web search, page inspection, DNS/RDAP lookup, archive lookup, evidence export, and two clearly separated Shodan operations. Even search_shodan vs lookup_shodan_host are easy to distinguish by indexed search vs. host-by-IP.
All tool names follow a consistent lower_snake_case verb_noun pattern. search_* indicates discovery-style tools, lookup_* indicates point lookups, and inspect_page/export_findings map one clear action to one clear object.
Eight tools is a well-scoped size for an OSINT investigation toolkit. Each tool adds a distinct source or capability, and there is no apparent bloat or thinness in the set.
The core investigation workflow is well covered: find subjects, search web and archives, inspect pages and domains, enrich with Shodan, and export evidence. Minor gaps remain around direct evidence record management and browser-level page inspection, but agents can work around them using the provided tools.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
An MCP server that gives your AI access to the source code and docs of all public github repos
