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., "@securitytrails-mcp What subdomains does example.com have?"
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.
An MCP server that gives an LLM agent the SecurityTrails API: DNS history, subdomain enumeration, WHOIS (current and historical), SSL certificates, and IPv4 intelligence — 17 read-only tools.
Built for reconnaissance work where the interesting question is usually "what did this look like before the CDN went up?" rather than "what does it resolve to now?".
Unofficial project. Not affiliated with, endorsed by, or sponsored by SecurityTrails or Recorded Future, Inc. You bring your own SecurityTrails API key and use it under your own agreement with them. See Legal.
You need a SecurityTrails API key — the free tier is enough to try it. Get one at securitytrails.com/app/account/credentials.
claude mcp add securitytrails --env SECURITYTRAILS_API_KEY=your_key -- npx -y securitytrails-mcp{
"mcpServers": {
"securitytrails": {
"command": "npx",
"args": ["-y", "securitytrails-mcp"],
"env": {
"SECURITYTRAILS_API_KEY": "your_key"
}
}
}
}Config file locations: Claude Desktop uses claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows);
Cursor uses ~/.cursor/mcp.json; VS Code uses .vscode/mcp.json in the workspace.
Related MCP server: domain-whois-mcp
Every tool is read-only, accepts response_format, and costs one SecurityTrails API query per
call — including per page when paging.
Tool | What it does | Plan |
| Check the API key is accepted | Free |
| Month-to-date consumption, allowance, remaining quota | Free |
| Current DNS records, hostname counts, registrar metadata | Free |
| Known subdomains as fully-qualified hostnames | Free |
| Domains sharing registrant details or infrastructure | Free |
| Historical A/AAAA/MX/NS/SOA/TXT records with observation dates | Free |
| Current WHOIS record | Free |
| Past WHOIS records — often pre-redaction | Free |
| Certificates issued for a hostname, including SAN entries | Free |
| SecurityTrails classification tags | Free |
| Adjacent IPv4 blocks, site counts, sample hostnames | Free |
| Network block registration, owner, abuse contacts | Free |
| Search the domain dataset by filter object or DSL query | Free |
| Search the IP dataset by filter object or DSL query | Free |
| Continue a search via its | Varies |
| User agents observed originating from an IPv4 address | Paid |
| IP ranges attributed to a domain's owning organisation | Paid |
Plan column reflects what a free-tier key could reach at the time of writing; SecurityTrails may move endpoints between tiers. The two paid endpoints return a clear plan error rather than a generic failure, so an agent knows to stop retrying:
Your SecurityTrails plan does not permit this endpoint (HTTP 403): This feature is not
available for your subscription package.Every tool takes response_format:
markdown (default) — a compact summary. Converts the API's raw Unix timestamps to dates,
drops null-filled privacy contacts, and appends a pagination footer saying whether more data
exists. Typically a fraction of the tokens of the equivalent JSON.
json — the untouched upstream payload, for when you need a field the summary omits.
If a payload does not match the shape a renderer expects, the server returns the raw JSON rather than a partial summary. A rendering gap will cost you tokens, never data.
The current A record is a CDN edge, so ask what it used to be:
> Has example.com always been behind Cloudflare? Check its A record history.// securitytrails_domain_details { "domain": "example.com" }
// securitytrails_dns_history { "domain": "example.com", "type": "a" }The history table shows each IP with the window it was observed in and the hosting organisation — an address that predates the CDN cutover is a candidate origin.
> I only know example.com. What else does this organisation own?// securitytrails_whois_current { "domain": "example.com" }
// securitytrails_associated { "domain": "example.com" }
// securitytrails_search_domains { "query": "whois_email = 'admin@example.com'" }WHOIS gives the registrant email; searching the dataset by that email finds every other domain
registered with it. securitytrails_whois_history is often more productive than the current
record, because older entries predate privacy redaction.
> Find hostnames for example.com that subdomain enumeration might have missed.// securitytrails_subdomains { "domain": "example.com", "limit": 1000 }
// securitytrails_ssl { "domain": "example.com", "status": "all", "include_subdomains": true }SAN entries on expired certificates frequently name internal or staging hosts that no longer
resolve. Use status: "all" — the default valid filter hides exactly the interesting ones.
> Who owns 8.8.8.8 and what else is in that block?// securitytrails_ip_whois { "ip": "8.8.8.8" }
// securitytrails_ip_neighbors { "ip": "8.8.8.8" }SecurityTrails bills per API query against a monthly allowance. securitytrails_usage reports
where you stand. Things worth knowing before pointing an agent at a large target:
securitytrails_subdomains costs one query regardless of result size. It returns the whole
set in a single call, so prefer one call with a high limit over paging with offset — paging
re-fetches and is billed again. Results default to 100 hostnames with total_count and
has_more always reported, so a truncated result is never mistaken for a complete one.
Paged endpoints cost one query per page. securitytrails_associated, _dns_history,
_ssl, _search_domains and _search_ips all bill per page.
The domain and IP datasets accept different DSL fields. ptr_part and open_port_80 are
IP-dataset fields; using them against securitytrails_search_domains is a syntax error, not an
empty result.
Each request has a 30-second timeout and retries twice on 429/5xx/network errors with
exponential backoff (500ms, then 1000ms). Non-transient failures — 400, 401, 403, 404 —
are never retried, so a bad argument costs one query rather than three.
Variable | Default | Purpose |
| (required) | Your API key |
|
| Per-attempt request timeout |
|
| Retries on 429/5xx/network errors |
If the key is missing the server still starts and still lists its tools, so the host shows it as
healthy; each tool call then returns an error naming the variable to set. This is deliberate — a
server that exits on startup shows up in most hosts as an unexplained crash. The key is validated
by use rather than by a startup ping, so that restarting your editor does not spend quota.
git clone https://github.com/aqhmal/securitytrails-mcp.git
cd securitytrails-mcp
npm install
npm test # 85 tests, no API key needed — the HTTP layer is stubbed
npm run build
npm run format # Prettier, in place
npm run inspect # build, then open the MCP Inspector against the serverThe suite drives a real MCP Client against the server in-process, so tool schemas, argument
validation, rendering and error handling are exercised through the actual protocol rather than by
calling handlers directly. See CONTRIBUTING.md.
Release history is in CHANGELOG.md.
evals/ holds a ten-question evaluation set for checking whether a model can actually accomplish
realistic lookups with these tools.
This is a reconnaissance tool. Only use it against infrastructure you are authorised to investigate.
The API key is read from the environment, sent only to api.securitytrails.com over HTTPS as a
header, and never logged, written to disk, or included in a tool result. Tool arguments are
validated with Zod before any request is made: hostnames must be bare hostnames, IPs must be
IPv4, and identifiers interpolated into request paths are percent-encoded, so a traversal
sequence cannot escape its endpoint.
To report a vulnerability, see SECURITY.md.
This is an unofficial, community-maintained client. It is not affiliated with, endorsed by, or sponsored by SecurityTrails, Recorded Future, Inc., or Mastercard.
SecurityTrails is a trademark of Recorded Future, Inc. (officially styled SecurityTrails, a Recorded Future Company). The name is used here only to identify the API this software talks to — nominative use — and no claim to the mark, and no sponsorship or endorsement, is made or implied. No SecurityTrails logos or brand assets are included or distributed with this project.
This project is a client. It ships no SecurityTrails data, and it grants you no rights to any. Your use of the API is governed entirely by your own agreement with SecurityTrails / Recorded Future, including their terms of service, your plan's query limits, and any restrictions on storing or redistributing what you retrieve. You are responsible for complying with those terms, and for only running reconnaissance against infrastructure you are authorised to investigate.
The MIT licence below covers this client's own source code and nothing else.
MIT © aqhmal
Find other domains associated with this one through shared registrant details or infrastructure. Useful for expanding scope from a single known domain to an organisation’s wider estate.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number; each page costs one API query | |
| domain | Yes | apex domain | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by explaining the association mechanism (shared registrant or infrastructure), which is beyond what annotations say. It does not disclose pagination costs beyond schema, but annotations cover 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?
Two sentences with no waste. The first sentence states the core functionality and mechanism; the second gives a clear use case. Efficiently communicates the tool's purpose.
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 (3 params, all documented), the description is nearly complete. It lacks explicit mention of pagination for large result sets, but the schema documents that. No output schema, but annotation openWorldHint indicates variable results. Could mention how results are ordered or returned, but not critical.
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 includes descriptions for each parameter. The description doesn't add much beyond that, but it implies the domain parameter is the starting point. Baseline 3 applies, but the description's mention of 'shared registrant details or infrastructure' clarifies the intent behind the domain parameter, nudging to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool finds associated domains via shared registrant details or infrastructure. Distinguishes from siblings like securitytrails_subdomains and securitytrails_company_associated_ips by focusing on domain-to-domain association.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it's for expanding scope from a single known domain to an organisation's wider estate. However, it doesn't contrast with alternatives like securitytrails_company_associated_ips or search_domains, which could also expand scope. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up IP addresses and ranges attributed to the organisation that owns a domain. Takes the company’s primary domain, not a company name. Requires a paid SecurityTrails plan — returns a plan error on the free tier.
| Name | Required | Description | Default |
|---|---|---|---|
| company_domain | Yes | the company’s primary domain, e.g. example.com | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it requires a paid plan and returns a plan error on the free tier, and it takes a domain rather than a company name. This is useful operational context.
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 sentences with zero waste. The core action and input constraint are front-loaded, and the plan requirement is stated concisely. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with 2 well-documented parameters and no output schema, the description is nearly complete. It covers the input constraint, the plan requirement, and the tool's purpose. The only minor gap is not describing what the output looks like, but since there's no output schema and the response_format parameter hints at markdown/json, this is acceptable.
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 both parameters well. The description adds the key semantic constraint that company_domain must be the primary domain, not a company name, which is useful. However, it doesn't add much beyond that since the schema already covers the 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 states a specific verb ('Look up') and resource ('IP addresses and ranges attributed to the organisation that owns a domain'), and clarifies the input is the company's primary domain, not a company name. This distinguishes it from sibling tools like securitytrails_ip_neighbors or securitytrails_search_ips.
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 on when to use the tool: when you need IPs attributed to the organization owning a domain. It also provides an exclusion ('not a company name') and a prerequisite (paid plan). It doesn't explicitly name alternative sibling tools, but the domain-based scope is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve historical values of one DNS record type for a domain, with the date range each value was observed. The primary tool for spotting infrastructure migrations and origin IPs that predate a CDN.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number; each page costs one API query | |
| type | Yes | DNS record type to retrieve history for | |
| domain | Yes | apex domain or hostname | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds a meaningful behavioral detail: the output includes the date range each value was observed, which goes beyond what annotations provide. No contradiction exists.
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 sentences with zero waste. The core action is front-loaded in the first sentence, and the use case is stated efficiently in the second. Every word 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?
The description explains what the tool does and its primary use case. The schema covers all parameters including pagination and response format. While there is no output schema, the response_format parameter lets the agent choose between markdown and JSON, and the description notes the date-range detail. For a read-only tool with clear parameters, this is adequately 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?
The input schema covers 100% of parameters with descriptions, including enums for type and response_format, page bounds, and domain pattern. The description adds no extra parameter semantics beyond what the schema already provides, so the baseline 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?
The description clearly states the tool retrieves historical DNS record values for a domain, including the date range each value was observed. It explicitly names the resource (DNS history) and distinguishes it from siblings by focusing on DNS rather than whois, subdomains, or other data types, and adds a specific use case (spotting infrastructure migrations and origin IPs predating CDN).
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 a concrete use case ('primary tool for spotting infrastructure migrations and origin IPs that predate a CDN'), telling when to use it. It does not explicitly contrast with sibling tools, but the name and description make it clear it's for DNS history rather than whois, subdomains, or other securitytrails tools, so context is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current DNS records (A, AAAA, MX, NS, SOA, TXT), hostname counts and registrar metadata for one domain. The best first call when profiling an unfamiliar domain.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | apex domain or hostname, e.g. example.com | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint false), so the description adds value by clarifying the current-snapshot scope, the single-domain constraint, and the categories of data returned. It does not cover potential caveats like caching or rate limits, but these are minor for a read-only lookup.
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 sentences with no wasted words. The core action and return contents are front-loaded, and the usage recommendation is appended as a single compact sentence.
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 two well-documented parameters, safety annotations, and no output schema, the description adequately summarizes what the caller receives: current DNS record types, hostname counts, and registrar metadata. The response_format behavior is already captured in the schema, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (domain and response_format) already have clear descriptions with format, default, and enum constraints. The tool description adds only the 'one domain' context, which is useful but does not meaningfully expand on the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Fetch'), a concrete resource (DNS records, hostname counts, registrar metadata), and explicitly enumerates the record types included. The phrase 'current DNS records' distinguishes it from the sibling securitytrails_dns_history, making the tool's role unmistakable.
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 statement 'The best first call when profiling an unfamiliar domain' gives an explicit, actionable use case and positions this tool early in a workflow. It does not name alternatives or explicitly state when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List IP blocks adjacent to the given IPv4 address, with the number of sites and sample hostnames seen on each. Useful for finding sibling infrastructure in the same allocation.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IPv4 address, e.g. 8.8.8.8 | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds useful behavioral context by explaining that output includes adjacent IP blocks, site counts, and sample hostnames, and it is fully consistent with the read-only annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler: the first states the action and output, the second provides the use case. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the essential purpose, output components, and use case. It does not detail the exact JSON response shape, but the schema covers parameters and the description gives enough for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'ip' and 'response_format' are already described in the input schema. The tool description provides no additional parameter-specific details, so the baseline 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?
The description states a specific action and resource: 'List IP blocks adjacent to the given IPv4 address' and names the output ('number of sites and sample hostnames'). It is clearly distinct from sibling IP tools like ip_whois or ip_useragents, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: 'Useful for finding sibling infrastructure in the same allocation.' This tells an agent when to use the tool, but it does not contrast it with alternatives such as search_ips or associated, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List user-agent strings SecurityTrails has observed originating from one IPv4 address, with first and last seen dates. Paginated. Requires a paid SecurityTrails plan — returns a plan error on the free tier.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IPv4 address | |
| page | No | 1-indexed page number; each page costs one API query | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: pagination behavior, the paid-plan requirement and its error consequence, and the fact that results are observed data with first/last seen dates. This goes beyond the annotations without contradicting them.
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 sentences with no filler. The core action and resource are front-loaded, followed by the pagination note and the plan requirement. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, paginated list tool with a fully documented schema, the description covers the essential context: what is returned, pagination, and the paid-plan constraint. It doesn't describe the exact response format, but there is no output schema and the response_format parameter lets the caller choose. The absence of an output schema is a minor gap, but the description is otherwise complete for an agent to decide whether to call 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?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the context that each page costs one API query, which is useful for the 'page' parameter, but it doesn't add much beyond the schema. 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 states a specific verb ('List'), a specific resource ('user-agent strings SecurityTrails has observed originating from one IPv4 address'), and includes the temporal fields ('first and last seen dates'). It clearly distinguishes from siblings like securitytrails_ip_neighbors or securitytrails_ip_whois by focusing on user agents observed on an IP.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions pagination and the paid-plan requirement, which gives context on when it can be used. It doesn't explicitly name alternatives or say when not to use it, but the sibling list and the specific resource make the use case clear. The plan error note is a useful exclusion for free-tier users.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch WHOIS and network-block registration data for one IPv4 address — owning organisation, allocation, and abuse contacts.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IPv4 address, e.g. 8.8.8.8 | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, so the description does not need to repeat those. It adds value by disclosing the actual data categories returned, including abuse contactsable, which helps the agent anticipate the response even without an output schema. No contradictions with annotations were found.
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 immediately states the action and object, then uses an em-dash to enumerate useful output fields. There is no filler, repetition of schema-only details, or unnecessary context.
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 tool with two well-documented parameters and no output schema, the description covers the essential details: what it fetches, for what input, and what data it returns. It is slightly incomplete in not mentioning any relationship to historical WHOIS or current-registration variants, but those are sibling-tool concerns already implied by the surrounding context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented including an example, pattern, enum, and default. The description adds no meaningful parameter-level detail beyond 'one IPv4', so the baseline score of 3 is appropriate because the schema already carries the semantic weight.
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 ('Fetch') and identifies the exact resource ('WHOIS and network-block registration data') plus the scope ('one IPv4 address'). It also lists concrete data contents (owning organisation, allocation, abuse contacts), making the tool's purpose unmistakable and distinguishing it from domain-focused WHOIS siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one IPv4 address' implies the tool is meant for single-IP WHOIS lookups, but there is no explicit guidance about when to use it instead of related tools like securitytrails_whois_current or securitytrails_whois_history. Usage context is clear by inference, but alternatives and exclusions are not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the configured SecurityTrails API key is accepted. Returns only a success flag — use securitytrails_usage for quota figures.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
| Name | Required | Description |
|---|---|---|
| success | Yes | true when the API key is valid |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds meaningful behavioral context by stating the return is 'only a success flag' and clarifying what the check verifies. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, information-dense sentences. The purpose is front-loaded, and the sibling-tool pointer is included without waste.
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?
Combined with rich annotations, a fully described optional parameter, and an output schema, the description covers everything an agent needs to select and invoke this tool correctly. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional parameter response_format is fully documented in the schema, including its enum and default. The description adds no parameter-level detail, so the baseline 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?
The description states a specific operation ('Check that the configured SecurityTrails API key is accepted') and clearly names the resource it acts on. It also distinguishes itself from securitytrails_usage by noting that only a success flag is returned.
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 for use (verifying API key acceptance) and explicitly routes quota-related needs to a sibling tool: 'use securitytrails_usage for quota figures.' This is direct and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the next batch of a large search using a scroll id. Only usable when a previous securitytrails_search_domains or securitytrails_search_ips response included meta.scroll_id — scrolling is not enabled on every plan or every query. When no scroll id is offered, page with the page argument instead.
| Name | Required | Description | Default |
|---|---|---|---|
| scroll_id | Yes | scroll id from a previous search response’s meta block | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context beyond that: scrolling is only available for certain plans/queries, and it fetches the next batch rather than re-running a search. No contradiction with annotations exists.
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 with no filler: the core action is front-loaded, the precondition follows, and the fallback behavior closes it. Every sentence 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?
The tool is simple with only two well-documented parameters and rich safety annotations. The description covers what the tool does, when it can be used, and what to do when it cannot be used, so nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description need not repeat parameter details. It does reinforce that scroll_id comes from a previous response's meta block, but that is already stated in the schema. The description adds no additional parameter meaning 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 a specific verb and resource: 'Fetch the next batch of a large search using a scroll id.' It distinguishes itself from the search tools by explicitly tying it to a previous search response's meta.scroll_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: only after securitytrails_search_domains or securitytrails_search_ips returns meta.scroll_id, and notes scrolling is not enabled on every plan/query. It also provides the alternative: use the page argument when no scroll id is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the domain dataset by structured filter or DSL query. Valid fields include apex_domain, keyword, tld, mx, ns, cname, ipv4, ipv6 and whois_email — for example {"apex_domain": "example.com"} or "whois_email = 'admin@example.com'". Note that the domain and IP datasets accept different field names: IP-only fields such as ptr_part or open_port_80 are a syntax error here, and belong in securitytrails_search_ips. Exactly one of filter or query is required. Each page costs one API query.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number; each page costs one API query | |
| query | No | DSL query string, e.g. "ipv4 = '1.2.3.4'" | |
| filter | No | structured filter object, e.g. {"apex_domain": "example.com"} | |
| include_ips | No | include resolved IPs for each domain | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (read-only, idempotent, non-destructive). The description adds valuable behavioral context: each page costs one API query, IP-only fields cause syntax errors, and the distinction between filter and query modes. This goes beyond what annotations provide, though it doesn't detail pagination behavior or error handling further.
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 efficient, starting with the core purpose, then the field list, then the critical distinction from IP search, then the requirement, and finally cost. Every sentence adds value with no redundancy or fluff.
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 5 parameters, no output schema, and a nested filter object, the description covers all essential aspects: what fields are valid, how to choose between filter and query, the cost per page, and the distinction from sibling tools. Return format is handled by the response_format parameter, so nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for each parameter, so baseline is 3. However, the description adds meaning beyond the schema by enumerating valid field names (apex_domain, keyword, tld, etc.) and clarifying that filter and query are mutually exclusive alternatives, which is not enforced by the schema itself. This compensates for the schema's generic propertyNames constraint.
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 the domain dataset using either a structured filter or DSL query, and explicitly distinguishes it from the IP search tool by noting IP-only fields cause errors and belong in securitytrails_search_ips. This makes the tool's purpose unambiguous and distinct from siblings.
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 explicitly says when to use this tool (for domain dataset), when not to (IP-only fields), and directs to the correct sibling. It also states the exact requirement that exactly one of `filter` or `query` must be provided, which is critical usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the IP dataset by DSL query or structured filter — for example "ptr_part = 'example'" or "open_port_80 = true". These IP-dataset fields are distinct from the domain-dataset fields used by securitytrails_search_domains. Exactly one of query or filter is required. Each page costs one API query.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number; each page costs one API query | |
| query | No | DSL query, e.g. "ptr_part = 'example'" | |
| filter | No | structured filter object | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds value by disclosing that each page costs one API query, which is a behavioral trait not captured in annotations. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It front-loads the core purpose, then provides examples, the sibling distinction, the required constraint, and the cost. Every sentence earns its place, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with four parameters, one nested object, and no output schema, the description covers the core purpose, usage constraints, cost, and differentiation from a key sibling. The response_format parameter is documented in the schema, so its omission from the description is acceptable. It could be more explicit about constructing the `filter` object, but the schema provides that structure, so this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by providing concrete examples for `query` (ptr_part = 'example') and `filter` (open_port_80 = true), and clarifies the mutually exclusive requirement of `query`/`filter`, which is not explicit in the schema. This helps the agent construct valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Search), the resource (IP dataset), and the method (DSL query or structured filter). It explicitly distinguishes this tool from the sibling securitytrails_search_domains by noting that the fields are distinct, so an agent can immediately tell them apart.
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 explicitly names the alternative tool (securitytrails_search_domains) and explains the distinction, guiding the agent on which to choose based on dataset. It also states the required constraint that exactly one of `query` or `filter` must be provided, and notes the cost per page, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List SSL/TLS certificates issued for a hostname. Subject alternative names in the results frequently reveal hostnames that subdomain enumeration alone misses. Pass status: "all" to include expired certificates, which are often the more interesting ones historically.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number; each page costs one API query | |
| domain | Yes | domain or subdomain | |
| status | No | certificate validity filter; use "all" when hunting historical hostnames | valid |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
| include_subdomains | No | also return certificates issued for subdomains of this host |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: results frequently expose SANs that are useful for discovery, and expired certificates are often historically interesting. This adds value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The primary purpose is front-loaded, followed immediately by the most valuable usage tip. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter, four optional ones, and full schema descriptions, the description covers the core purpose, a key use-case insight, and a parameter recommendation. Return format and pagination are already explained in the schema. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented in the schema. The description goes further by advising to pass status='all' for historical hostname hunting, which directly aids parameter selection and adds meaning beyond the schema's generic enum description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List SSL/TLS certificates issued for a hostname') and immediately distinguishes its value from sibling tools by highlighting SANs as a discovery vector beyond subdomain enumeration. No ambiguity about what the tool returns.
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 clear context on when the tool is valuable (revealing hostnames subdomain enumeration misses) and hints at the historical use case with expired certificates. Does not explicitly name sibling alternatives or exclusions, but the context is sufficient for an agent to infer when to prefer this tool over subdomain enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known subdomains of a domain as fully-qualified hostnames, ready to feed into resolution or scanning. Costs one API query regardless of how many hostnames exist, so prefer a single call with a high limit over paging with offset — each page is separately billed. The response always reports total_count and has_more so a truncated result is never mistaken for a complete one.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | maximum hostnames to return (default 100) | |
| domain | Yes | apex domain, e.g. example.com | |
| offset | No | number of hostnames to skip before returning | |
| children_only | No | only direct children (one label deep) rather than the full tree | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
| include_inactive | No | include subdomains with no current DNS resolution |
| Name | Required | Description |
|---|---|---|
| apex | Yes | |
| note | No | |
| limit | Yes | |
| offset | Yes | |
| has_more | Yes | |
| returned | Yes | |
| hostnames | Yes | fully-qualified hostnames |
| next_offset | No | offset to pass for the next page, when has_more |
| total_count | Yes | total subdomains SecurityTrails holds for this apex |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds substantial behavioral context: the cost model (one API query per call, each page separately billed) and the invariant that responses always include `total_count` and `has_more` so truncation is never hidden. These details go beyond what the annotations convey and help the agent plan efficient calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each with a distinct purpose: what the tool does, how to use it efficiently, and what to expect from the response. There is no filler and no redundancy with the schema.
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 a 6-parameter schema with 100% description coverage, an output schema, and safety-relevant annotations, the description covers the non-obvious operational details (billing, pagination, truncation detection) that an agent needs. Nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the billing trade-off between `limit` and `offset` and by telling the agent that `total_count` and `has_more` are always present, which informs parameter choices. It does not repeat each parameter's schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('known subdomains of a domain') and specifies the output as 'fully-qualified hostnames, ready to feed into resolution or scanning.' This clearly distinguishes it from sibling tools like securitytrails_dns_history or securitytrails_domain_details, which address different 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 description provides clear context for when to use the tool ('ready to feed into resolution or scanning') and gives concrete, actionable guidance: prefer a single high-limit call over paging with offset because each page is billed separately. It does not explicitly name alternatives or exclusions, but the usage direction is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return SecurityTrails’ classification tags for a domain. Many domains carry no tags at all.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | apex domain or hostname | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect profile. The description adds a valuable behavioral note: 'Many domains carry no tags at all,' which sets expectations about possible empty results. This goes beyond the annotations, though it does not cover rate limits or auth (not required given the read-only, idempotent nature).
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 sentences with zero filler. It leads with the core action, then adds a relevant caveat. Every word earns its place, and it is appropriately 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 lookup tool with two well-documented parameters and annotations covering safety, the description is sufficient. It states the purpose, the empty-case behavior, and the response_format is self-explanatory from the schema. No output schema exists, but the tool's output (tags) is implied. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both domain and response_format have descriptions in the schema. The tool description adds no additional parameter semantics beyond what the schema already provides. With high coverage, the baseline is 3, and the description does not elevate 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 states a clear, specific action: 'Return SecurityTrails’ classification tags for a domain.' This is a distinct verb+resource and the name aligns. However, it does not explicitly contrast with sibling tools (e.g., domain_details, whois), so an agent must infer that tags are the sole focus. Still, the purpose is unambiguous and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling tools (securitytrails_domain_details, securitytrails_subdomains, etc.). The description does not mention alternatives, conditions, or exclusions. It only states what it does, leaving the agent to guess that it is specifically for tag lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report this month’s SecurityTrails API consumption against the plan allowance. Call this before a large enumeration to confirm there is remaining quota.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
| Name | Required | Description |
|---|---|---|
| remaining | Yes | allowance minus consumption |
| percent_used | Yes | consumption as a percentage, rounded to one decimal place |
| allowed_monthly_usage | Yes | queries included in the plan per month |
| current_monthly_usage | Yes | queries consumed so far this month |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context beyond annotations: it reveals the tool reports against a plan allowance and is intended as a pre-flight check, which is exactly the kind of supplementary context that earns value here. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: purpose is front-loaded, usage guidance follows immediately, and there is no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple informational tool with a rich output schema, full parameter documentation, and comprehensive annotations, nothing an agent needs to call it correctly is missing. The timing guidance completes the picture for a quota-check utility.
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%, and the single optional parameter (response_format) is fully documented with enum values and descriptions in the schema itself. Per the baseline rule, the description need not repeat parameter details, so a 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 opens with a specific verb and resource ('Report this month's SecurityTrails API consumption against the plan allowance'), making the tool's function unambiguous. It is clearly distinct from all 16 siblings, none of which address quota or plan allowance, so an agent can immediately tell this is the quota-check tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives explicit timing guidance ('Call this before a large enumeration to confirm there is remaining quota'), which tells the agent when to invoke it. It does not name specific alternatives or state when not to use it, but the sibling set makes the exclusive purpose clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current WHOIS record for a domain: registrar, registrant contacts where not redacted, nameservers, and creation/expiry dates.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | apex domain | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about the returned fields and the 'where not redacted' caveat, which is useful but minimal. It does not cover rate limits, auth, or error behavior, though those are less critical given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource, then lists the expected output fields. No filler or repetition. It earns the maximum for efficiency.
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 (2 params, no output schema) and the annotations covering safety, the description is nearly complete. It lists the main data categories returned, mentions redaction, and differentiates current vs historical. It lacks explicit error/not-found handling, but that is a minor gap for a lookup tool of this nature.
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%: both parameters have detailed descriptions (domain pattern and response_format enum). The description text itself does not add extra meaning beyond what the schema provides, so the baseline 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?
The description states a specific verb ('Fetch'), a specific resource ('current WHOIS record'), and enumerates the key data fields (registrar, registrant contacts, nameservers, dates). It clearly distinguishes from siblings like whois_history (historical) and ip_whois (IP-based) by the word 'current'.
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 current-data use case but does not explicitly contrast with alternatives. It says 'current WHOIS' which hints at the historical sibling, but it never names when-not-to-use or other conditions (e.g., for full domain details use domain_details). The guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve past WHOIS records for a domain, each with the window it was observed in. Historical records often expose registrant details that have since been redacted behind privacy services.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | apex domain | |
| response_format | No | "markdown" for a compact human-readable summary, "json" for the full raw API payload | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=falseching, so the description need not restate safety. It adds useful context by noting each record includes the observation window and that historical records may reveal previously redacted registrant details, but it does not go deeper into rate limits or data availability.
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 sentences with no filler. The first sentence defines what the tool does Bennett, and the second explains why historical data is valuable. Both earn their place and the key operational detail ('past WHOIS records', 'window it was observed in') 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 tool with only one required parameterebb, the description is largely complete: it explains the purpose, the result type (past records with observation windows), and the likely motivation for using it. The lack of an output schema is partially offset by the mention of observation windows and the response_format parameter.
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 description coverage is 100% for both parameters, so the baseline is 3. The description does not add additional meaning beyond what the schema already explains for 'domain' and 'response_format'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Retrieve past WHOIS records for a domain.' The word 'Historical' in the title and 'past' in the description clearly contrast with the sibling tool 'securitytrails_whois_current', so an agent can distinguish the two, though the description does not explicitly name the sibling.
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 a concrete use case: historical records may expose registrant details that are now redacted. However, it does not explicitly say when to use this tool instead of the current WHOIS tool, nor does it mention exclusions or alternatives.
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.1securitytrails_associatedsecuritytrails_company_associated_ipssecuritytrails_dns_historysecuritytrails_domain_detailssecuritytrails_ip_neighborssecuritytrails_ip_useragentssecuritytrails_ip_whoissecuritytrails_pingsecuritytrails_scrollsecuritytrails_search_domainssecuritytrails_search_ipssecuritytrails_sslsecuritytrails_subdomainssecuritytrails_tagssecuritytrails_usagesecuritytrails_whois_currentsecuritytrails_whois_historyScored across 17 tools
Each tool targets a distinct resource or action: WHOIS, DNS, subdomains, history, SSL, IP data, and search are clearly separated. The only potential overlap is domain_details vs whois_current, but the descriptions make their scopes explicit (DNS vs WHOIS record). No two tools appear to serve the same purpose.
All tools share the 'securitytrails_' prefix and use snake_case, which is consistent. However, some names are nouns (ping, usage, tags) while others are verb_noun (search_domains, get_domain_details implied), so the pattern is not uniformly verb-first. Minor deviation but still predictable and readable.
17 tools is on the heavier side but appropriate for the breadth of SecurityTrails' API (WHOIS, DNS, subdomains, IP intelligence, search). Each tool covers a meaningful function; the count reflects the domain's scope rather than redundancy. It sits just above the ideal range but remains well-scoped.
The tool surface covers the major SecurityTrails capabilities: current and historical WHOIS/DNS, subdomain enumeration, associated domains, SSL certificates, IP information, and flexible search with scrolling. There are no obvious dead ends—quota checks and paging support are included. The API's core workflows appear fully represented.
20 domain recon tools for AI agents: DNS, SSL, headers, email, subdomains, lookalikes, changes.
Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
SEO research, audits, backlinks, GSC, and content workflow tools for AI agents.
29 pay-per-call DNS, SEO, SSL, security, and dev tools for AI agents. x402, no API key.
