SecurityScorecard MCP Server integrates with the SecurityScorecard API to provide security scoring, risk analysis, and asset management tools for MCP-compatible clients. It offers: a security dashboard with score, grade, and metrics; risk analysis and prioritization (critical/all/quick-wins) with remediation guidance; improvement plan generation with timelines (30-day, 90-day, 6-month) and target grades (C/B/A); asset discovery for domains and IPs with security context; email security analysis (SPF, DMARC, DKIM); API discovery across 517 SecurityScorecard endpoints using hybrid semantic/keyword search; issue type analysis (DNS health, application security, network security, etc.); data completeness validation; and direct API queries with validation and parameter hints. Tools support minimal/standard/detailed response modes, work with MCP clients (Claude Desktop, Claude Code, Cursor, VS Code), run via stdio, and can be installed from npm with npx using a SecurityScorecard API token.
Integrates with the SecurityScorecard API to provide security rating tools, including score and grade retrieval, risk analysis, remediation planning, asset discovery, email security analysis (SPF/DMARC/DKIM), API endpoint discovery, issue type breakdowns, and direct API queries.
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., "@SecurityScorecard MCP Server show me the security grade for example.com"
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 community-built, comprehensive Model Context Protocol (MCP) server that integrates with the SecurityScorecard API. It runs over stdio, so it works with any MCP-compatible client — Claude Desktop, Claude Code, Cursor, VS Code, and others.
Published on npm as
@callmarcus/securityscorecard-mcpand listed in the MCP Registry asio.github.CallMarcus/securityscorecard-mcp.
Disclaimer: This is an independent, community-built open-source project. It is not affiliated with, endorsed by, sponsored by, or associated with SecurityScorecard, Inc. in any way. It is built solely against SecurityScorecard's publicly available API documentation. "SecurityScorecard" and all related names, marks, and logos are trademarks of SecurityScorecard, Inc. and are used here for identification purposes only. You must supply your own API credentials and comply with SecurityScorecard's terms of service.
Node.js 20+ - Download
SecurityScorecard API Token - Get from your SecurityScorecard dashboard
No clone or build required. The server runs over stdio via npx, so any MCP-compatible client can launch it. npx -y always fetches the latest published version.
Most clients — Claude Desktop, Cursor, Cline, Windsurf, and others — share the same mcpServers JSON. Add this block to the client's MCP config:
{
"mcpServers": {
"security-scorecard": {
"command": "npx",
"args": ["-y", "@callmarcus/securityscorecard-mcp"],
"env": {
"SECURITY_SCORECARD_API_TOKEN": "your-api-token-here",
"COMPANY_DOMAIN": "example.com"
}
}
}
}Where that config file lives:
Client | Config file |
Claude Desktop (Windows) |
|
Claude Desktop (macOS) |
|
Cursor |
|
Replace the credentials with your own, then restart the client.
Claude Code — add it from the CLI instead:
claude mcp add security-scorecard \
--env SECURITY_SCORECARD_API_TOKEN=your-api-token-here \
--env COMPANY_DOMAIN=example.com \
-- npx -y @callmarcus/securityscorecard-mcpOn Windows, wrap the launcher in cmd /c: ... -- cmd /c npx -y @callmarcus/securityscorecard-mcp.
VS Code (Copilot) — uses a servers key with an explicit type, in .vscode/mcp.json:
{
"servers": {
"security-scorecard": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@callmarcus/securityscorecard-mcp"],
"env": {
"SECURITY_SCORECARD_API_TOKEN": "your-api-token-here",
"COMPANY_DOMAIN": "example.com"
}
}
}
}# Clone the repository
git clone https://github.com/CallMarcus/security-scorecard-mcp.git
cd security-scorecard-mcp
# Install dependencies
npm install
# Build (use build:fast to avoid memory issues)
npm run build:fastThen point your MCP client at the local build. For clients that use the mcpServers format (Claude Desktop, Cursor, …):
{
"mcpServers": {
"security-scorecard": {
"command": "node",
"args": ["/path/to/security-scorecard-mcp/build/index.js"],
"env": {
"SECURITY_SCORECARD_API_TOKEN": "your-api-token-here",
"COMPANY_DOMAIN": "example.com"
}
}
}
}Important: Replace the path and credentials with your actual values, then restart your MCP client. (For Claude Code, run claude mcp add security-scorecard --env SECURITY_SCORECARD_API_TOKEN=your-api-token-here -- node /path/to/security-scorecard-mcp/build/index.js.)
Related MCP server: scorecard_mcp
The server (index.js) provides 9 specialized tools:
Tool | Purpose |
| Score, grade, and key security metrics |
| Issue prioritization and risk analysis |
| Actionable remediation roadmaps |
| Asset inventory with security context |
| SPF/DMARC/DKIM analysis |
| Search 517 API endpoints with hybrid semantic/keyword search |
| Granular issue type breakdowns |
| Cross-tool data verification |
| Direct API access with discovery |
Each tool supports three response modes for token efficiency:
minimal - Quick answers (15-50 tokens)
standard - Overview with context (200-300 tokens)
detailed - Comprehensive analysis (800+ tokens)
Variable | Required | Description |
| Yes | Your API token |
| No | Default domain for queries |
| No | Set |
Optional rate limiting and caching:
REQUEST_CACHE_TTL_MS=300000
REQUESTS_PER_INTERVAL=5
REQUEST_INTERVAL_MS=1000The server includes hybrid search (semantic + keyword) for finding SecurityScorecard API endpoints:
Use api_discovery to search for "email security"This searches 517 indexed endpoints and returns matching paths with confidence scores, required parameters, and curl examples.
To update the API reference after changes:
npm run api:embed # Regenerate semantic embeddings
npm run api:update # Regenerate docs + embeddingsnpm run build:fast # Recommended - uses esbuild (~130ms)
npm run build # TypeScript compiler (may OOM on some systems)
npm test # Run testssrc/
index.ts # MCP server (9 tools)
api/client.ts # SecurityScorecard API client
integration/ # API discovery system
docs/api/ # Self-contained API reference
index.jsonl # Endpoint index (517 endpoints)
index-embeddings.json # Semantic search embeddings
build/ # Compiled JavaScriptnpm test # Run test suiteUse the fast build instead:
npm run build:fastReinstall dependencies:
rm -rf node_modules
npm install
npm run build:fastInstall for the platform that runs the server. Claude Desktop on Windows
launches the server with Windows node, so if npm install ran under WSL
the native modules (onnxruntime-node, sharp) only have linux binaries —
the embeddings layer fails to load and api_discovery silently degrades to
keyword-only search (results still come back, but confidence scoring is
cruder). Run npm install && npm run build:fast from PowerShell or cmd in
the repo directory instead — or keep two clones, one per platform.
Double-check the config file location for your client (see Quick Start)
For a from-source install, verify the path to build/index.js is correct
Restart the client completely
Sanity-check that the server starts on its own: npx -y @callmarcus/securityscorecard-mcp (it should launch and wait silently on stdio)
Your API token is invalid or expired. Get a new one from SecurityScorecard dashboard.
MIT
📧 EMAIL SECURITY: Analyze SPF, DMARC, DKIM issues with domain-by-domain breakdown and cross-validation. INTELLIGENT RESPONSES: Use 'minimal' for simple counts like 'how many SPF missing?' (10-30 tokens). Use 'standard' for email security overview (200-400 tokens). Use 'detailed' for comprehensive email analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Company domain to analyze | example.com |
| response_mode | No | Response detail level | minimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It fails to disclose behavioral traits such as whether external DNS lookups are performed, authentication requirements, rate limits, or side effects. The description only mentions analysis and cross-validation without safety or operational details.
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 two clear blocks: purpose and response mode guidance. It is front-loaded with the core purpose. The emoji and caps are minor style choices but do not hinder clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the input and response modes well but does not describe the output format or structure, which would be important given no output schema. It mentions 'domain-by-domain breakdown' but lacks specificity on what the output contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds significant value by explaining the meaning of each response_mode option (e.g., minimal for simple counts like 'how many SPF missing?') and providing token length estimates, going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes SPF, DMARC, and DKIM issues with domain-by-domain breakdown and cross-validation, making the purpose specific and distinct from sibling tools like security_dashboard or analyze_security_risks.
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 explicit guidance for using response modes (minimal, standard, detailed) with token counts, but does not provide any guidance on when to use this tool versus sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 ISSUE BREAKDOWN: Get detailed breakdown of security issues by specific types (SPF, DMARC, patching, etc.). INTELLIGENT RESPONSES: Use 'minimal' for specific counts (20-50 tokens). Use 'standard' for issue type summary (200-300 tokens). Use 'detailed' for comprehensive breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Company domain to analyze | example.com |
| focus_factor | No | Focus on specific security factor | all |
| response_mode | No | Response detail level | minimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions token estimates for responses and describes output detail levels, but does not disclose read-only nature, authentication needs, rate limits, or potential side effects.
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 short and front-loaded with key information. Emojis and capitalization highlight important points, though the structure is slightly informal. No unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no annotations, the description adequately covers the tool's function and response modes. However, it could benefit from mentioning expected output format or example usage for completeness.
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 explains each parameter. The description adds context for response_mode by linking it to output length but does not enhance understanding of domain or focus_factor 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 specifies a clear action ('Get detailed breakdown') and resource ('security issues by specific types' like SPF, DMARC), distinguishing it from sibling tools like analyze_security_risks or analyze_email_security.
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 guidance on using the response_mode parameter ('minimal', 'standard', 'detailed') but does not explain when to choose this tool over sibling tools, such as for a high-level risk assessment vs. type-specific breakdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🚨 SECURITY RISKS: Comprehensive security risk analysis with intelligent prioritization. Analyzes critical vulnerabilities, risk patterns, and provides actionable remediation guidance with flexible response modes.
| Name | Required | Description | Default |
|---|---|---|---|
| focus | No | Focus area: critical (high/critical issues only), all (complete analysis), quick-wins (easy fixes) | all |
| domain | No | Company domain to analyze (e.g., example.com) | example.com |
| response_mode | No | Response detail level: minimal (50-100 tokens), standard (300-500 tokens), detailed (comprehensive) | minimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It states that it analyzes risks and provides remediation guidance, implying a read-only operation, but does not explicitly confirm non-destructiveness, mention required permissions, rate limits, or any side effects. The lack of a clear safety profile is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with an emoji prefix. While not overly verbose, it includes some promotional fluff ('🚨 SECURITY RISKS') and could be more information-dense by removing the emoji and adding more specific behavioral or usage details. It is concise but not optimally structured for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate complexity (3 parameters, all optional, with enums), the description should explain what the tool returns and any context about the analysis output. It only mentions 'actionable remediation guidance' but does not detail the structure (e.g., list of risks, priorities, scores). Missing information on authentication or prerequisites also contributes to incompleteness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good parameter descriptions in the schema (e.g., focus enum values, domain example, response_mode token ranges). The description adds minimal value by mentioning 'flexible response modes' and 'intelligent prioritization', which loosely echo the focus and response_mode parameters. Since schema already covers semantics well, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs comprehensive security risk analysis with intelligent prioritization and provides actionable remediation guidance. It distinguishes itself by focusing on risk analysis and prioritization, but does not explicitly differentiate from sibling tools like security_dashboard or analyze_issue_types.
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 lacks any guidance on when to use this tool versus alternatives. It does not specify prerequisites, when to choose different focus areas (critical, all, quick-wins) or response modes, or mention any constraints or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and discover SecurityScorecard API endpoints. Returns both human-readable summary and structured JSON for programmatic use.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by API tag/category (e.g., 'Companies', 'Portfolios', 'Issues') | |
| limit | No | Maximum number of results to return | |
| query | Yes | Search query for API endpoints (e.g., 'security score', 'vulnerabilities', 'company data') | |
| method | No | Filter by HTTP method | |
| include_schema | No | Include detailed request/response schema for top result |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses return format (human-readable and structured JSON) but lacks explicit statement about side effects or read-only nature. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that efficiently convey purpose and return format without any superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 5 parameters and no output schema, the description provides enough high-level context. However, more detail on return structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description adds no significant meaning beyond the schema, so 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 that the tool searches and discovers SecurityScorecard API endpoints, distinguishing it from sibling tools that focus on other tasks like dashboards, risks, or assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding API endpoints but does not explicitly specify when to use it over alternatives. However, since sibling tools have different purposes, the context is clear without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🎯 IMPROVEMENT PLAN: Generate security improvement recommendations. INTELLIGENT RESPONSES: Use 'minimal' for simple questions like 'what should I fix first?' (50-100 tokens). Use 'standard' for improvement summary (300-500 tokens). Use 'detailed' for full roadmap.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Company domain to analyze | example.com |
| timeline | No | Timeline for improvement | 90-days |
| target_grade | No | Target security grade | A |
| response_mode | No | Response detail level | minimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It only mentions response modes and token counts, but fails to state whether the tool has side effects, requires specific permissions, or if it is read-only. Missing critical context for safe invocation.
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?
Very concise: two sentences with clear structure. Front-loaded with purpose, then response mode guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers response modes well, it lacks information about output format (no output schema) and prerequisites (e.g., need prior analysis). Given no output schema and 4 params, more context would be helpful for agent completion.
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 parameters. The description adds token count guidance for response_mode, but does not significantly enhance other parameter meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Generate security improvement recommendations' with a specific verb and resource. It distinguishes from sibling tools like analyze_security_risks by focusing on generating a plan rather than analyzing risks.
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 explicit guidance on when to use each response mode ('minimal' for simple questions, 'standard' for summary, 'detailed' for full roadmap). However, it does not explicitly say when to use this tool versus alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
🔍 ASSET INVENTORY: Discover domains and IPs with security context and data completeness validation. INTELLIGENT RESPONSES: Use 'minimal' for simple questions like 'how many assets?' (20-50 tokens). Use 'standard' for asset overview (200-400 tokens). Use 'detailed' for comprehensive inventory.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Parent domain to discover assets for | example.com |
| response_mode | No | Response detail level | minimal |
| include_risk_details | No | Include security risk information |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes a read-like discovery operation but does not mention side effects, authentication needs, rate limits, or whether it is safe. The response mode hints at token consumption but lacks full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with two clear sections, but uses excessive all-caps and emojis which reduce readability. It is somewhat verbose in the response_mode section; could be tightened while retaining key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify return values. It mentions 'security context and data completeness validation' but does not describe the response structure or how it differs from sibling outputs. Agent lacks understanding of what exactly is returned.
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?
Input schema covers 100% of parameters, but the description adds value by explaining the response_mode enum with concrete token ranges and usage examples, going beyond the schema's basic description. This helps the agent choose appropriate detail levels.
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 title 'Asset Discovery' and description explicitly state it discovers domains and IPs with security context and data completeness validation. It clearly distinguishes from sibling tools like security_dashboard or analyze_security_risks.
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 guidance on using different response modes ('minimal', 'standard', 'detailed') with token estimates, which helps with parameter selection. However, it does not advise when to choose this tool over siblings like analyze_security_risks or validate_data_completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Direct API access with smart endpoint validation. Uses API discovery to validate endpoints, suggest alternatives, and provide parameter hints.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Domain to use in endpoint | example.com |
| method | No | HTTP method | GET |
| endpoint | Yes | API endpoint to query (e.g., /companies/{domain}/factors) | |
| validate_only | No | Only validate endpoint without calling API |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It mentions 'Direct API access' implying network calls, but fails to state whether operations are read-only, authentication needs, rate limits, or side effects.
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, front-loaded with purpose. Each sentence adds value; no wasted words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is incomplete. It does not explain return values, error handling, or validation details. Sibling tools lack clear differentiators, leaving the tool's context underdefined.
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 baseline is 3. The description adds 'smart endpoint validation' and 'parameter hints' context, but does not significantly enhance understanding beyond the schema's parameter descriptions.
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 'Direct API access with smart endpoint validation,' clearly indicating it queries a security API. It distinguishes itself from siblings like 'security_dashboard' by emphasizing direct API use, but lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings like 'security_dashboard' or 'analyze_security_risks'. The description mentions 'suggest alternatives' but does not provide explicit when-to or when-not-to use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
📊 SECURITY STATUS: Get comprehensive security score, grade, and key metrics with intelligent response modes. Supports minimal responses for quick queries and detailed analysis for comprehensive security overviews.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Company domain to analyze (e.g., example.com) | example.com |
| response_mode | No | Response detail level: minimal (10-20 tokens), standard (200-300 tokens), detailed (800+ tokens) | minimal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'intelligent response modes' but lacks details on authentication, rate limits, or whether the operation is read-only, leaving behavioral traits mostly undisclosed.
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, front-loaded with an emoji and clear purpose, with no redundant information. Every sentence contributes 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?
Given the tool's simplicity (2 parameters, no output schema), the description adequately covers its purpose and response modes. However, it lacks detail about the output structure, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description adds no new semantics beyond the schema, simply restating the response_mode enum. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a comprehensive security score, grade, and key metrics, distinguishing it from sibling tools like 'analyze_security_risks' and 'create_improvement_plan' that focus on deeper analysis or planning.
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 hints at usage contexts through response modes (minimal for quick queries, detailed for comprehensive overviews) but does not explicitly compare to alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
✅ DATA VALIDATION: Cross-validate tool results for accuracy and completeness. INTELLIGENT RESPONSES: Use 'minimal' for validation status (25 tokens). Use 'standard' for validation summary (200-400 tokens). Use 'detailed' for full data audit.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Company domain to validate | example.com |
| response_mode | No | Response detail level | minimal |
| expected_asset_count | No | Expected number of assets for validation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool cross-validates tool results but does not mention effect on data, auth requirements, rate limits, or consequences of failure. This is insufficient for a mutation-like validation operation.
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 short (two sentences) but uses heavy formatting (emojis, caps) that adds noise. Key information on response modes is present but could be more succinct and structured, e.g., using bullet points.
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 lacks explanation of what 'validation' entails, what return format to expect (no output schema), or how to interpret results. Given 3 parameters and no annotations, more detail on behavior and outputs is needed for an AI to invoke 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 coverage is 100%, providing a baseline of 3. The description adds valuable context beyond the schema by specifying token counts for each response_mode (e.g., 'minimal' uses 25 tokens), enabling the AI to estimate cost and latency.
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 validates data completeness and accuracy, but it does not explicitly differentiate from sibling tools like 'analyze_security_risks' or 'discover_assets'. The name and title align well, so purpose is clear but sibling distinction is missing.
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 guidance on choosing response modes with token size hints, which helps the AI select appropriate verbosity. However, it lacks explicit 'when to use' vs. alternatives or any context about prerequisites or ordering relative to other tools.
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.1.1analyze_email_securityanalyze_issue_typesanalyze_security_risksapi_discoverycreate_improvement_plandiscover_assetsquery_security_datasecurity_dashboardvalidate_data_completenessScored across 9 tools
Tools have mostly distinct purposes (dashboard, risks, assets, email, etc.), but security_dashboard and analyze_security_risks could be confused by an agent as both provide security overviews, though descriptions help differentiate.
All tool names use consistent snake_case and follow a clear verb_noun pattern (e.g., analyze_*, create_*, discover_*), making it easy to predict function.
9 tools is well-scoped for a security rating API; each tool addresses a distinct aspect without being too few or too many.
Covers core security assessment lifecycle (grade, risks, improvement, assets, email, issues) plus API discovery and validation. Missing historical trend analysis but still functional.
Threat intel + your scans/findings/Shield posture. CVE, EPSS, KEV, package vuln lookup, DAST.
Security reviews, threat models over a repo or website, and remediation tracking, in your editor.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Threat modeling, code/cloud/pipeline scanning, shadow-AI discovery, compliance checks and fixes.
