该项目为流行的开源漏洞管理工具DefectDojo提供了一个模型上下文协议 (MCP)服务器实现。它允许 AI 代理和其他 MCP 客户端以编程方式与 DefectDojo API 进行交互。
该 MCP 服务器公开了用于管理关键 DefectDojo 实体的工具：
**发现：**获取、搜索、创建、更新状态和添加注释。
**产品：**列出可用的产品。
**约定：**列出、检索详细信息、创建、更新和结束约定。
Related MCP server: NIST NVD MCP Server
有几种方法可以运行此服务器：
uvx （推荐）uvx在临时虚拟环境中执行 Python 应用程序，自动安装依赖项。
uvx defectdojo-mcppip您可以使用pip将包安装到您的 Python 环境中。
# Install directly from the cloned source code directory
pip install .
# Or, if the package is published on PyPI
pip install defectdojo-mcp通过 pip 安装后，使用以下命令运行服务器：
defectdojo-mcp服务器需要以下环境变量来连接到您的 DefectDojo 实例：
DEFECTDOJO_API_TOKEN （必需）：用于身份验证的 DefectDojo API 令牌。
DEFECTDOJO_API_BASE （必需）：您的 DefectDojo 实例的基本 URL（例如， https://your-defectdojo-instance.com ）。
您可以在 MCP 客户端的设置文件中配置这些。以下是使用uvx命令的示例：
{
"mcpServers": {
"defectdojo": {
"command": "uvx",
"args": ["defectdojo-mcp"],
"env": {
"DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE",
"DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
}
}
}
}如果您使用pip安装该软件包，则配置将如下所示：
{
"mcpServers": {
"defectdojo": {
"command": "defectdojo-mcp",
"args": [],
"env": {
"DEFECTDOJO_API_TOKEN": "YOUR_API_TOKEN_HERE",
"DEFECTDOJO_API_BASE": "https://your-defectdojo-instance.com"
}
}
}
}可通过 MCP 界面使用以下工具：
get_findings ：通过过滤（产品名称、状态、严重性）和分页（限制、偏移）检索结果。
search_findings ：使用文本查询搜索结果，并进行过滤和分页。
update_finding_status ：更改特定发现的状态（例如，活动、已验证、误报）。
add_finding_note ：为发现添加文本注释。
create_finding ：创建与测试相关的新发现。
list_products ：列出具有过滤（名称、产品类型）和分页功能的产品。
list_engagements ：列出带有过滤（product_id、status、name）和分页的参与度。
get_engagement ：通过 ID 获取特定参与的详细信息。
create_engagement ：为产品创建新的约定。
update_engagement ：修改现有约定的详细信息。
close_engagement ：将约定标记为已完成。
（每个工具的详细使用示例请见下方README原文内容）
（注意：这些示例假设 MCP 客户端环境能够调用use_mcp_tool ）
# Get active, high-severity findings (limit 10)
result = await use_mcp_tool("defectdojo", "get_findings", {
"status": "Active",
"severity": "High",
"limit": 10
})# Search for findings containing 'SQL Injection'
result = await use_mcp_tool("defectdojo", "search_findings", {
"query": "SQL Injection"
})# Mark finding 123 as Verified
result = await use_mcp_tool("defectdojo", "update_finding_status", {
"finding_id": 123,
"status": "Verified"
})result = await use_mcp_tool("defectdojo", "add_finding_note", {
"finding_id": 123,
"note": "Confirmed vulnerability on staging server."
})result = await use_mcp_tool("defectdojo", "create_finding", {
"title": "Reflected XSS in Search Results",
"test_id": 55, # ID of the associated test
"severity": "Medium",
"description": "User input in search is not properly sanitized, leading to XSS.",
"cwe": 79
})# List products containing 'Web App' in their name
result = await use_mcp_tool("defectdojo", "list_products", {
"name": "Web App",
"limit": 10
})# List 'In Progress' engagements for product ID 42
result = await use_mcp_tool("defectdojo", "list_engagements", {
"product_id": 42,
"status": "In Progress"
})result = await use_mcp_tool("defectdojo", "get_engagement", {
"engagement_id": 101
})result = await use_mcp_tool("defectdojo", "create_engagement", {
"product_id": 42,
"name": "Q2 Security Scan",
"target_start": "2025-04-01",
"target_end": "2025-04-15",
"status": "Not Started"
})result = await use_mcp_tool("defectdojo", "update_engagement", {
"engagement_id": 101,
"status": "In Progress",
"description": "Scan initiated."
})result = await use_mcp_tool("defectdojo", "close_engagement", {
"engagement_id": 101
})克隆存储库。
建议使用虚拟环境：
python -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`安装依赖项，包括开发依赖项：
pip install -e ".[dev]"该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。
欢迎贡献！欢迎随时提交问题，包括错误报告、功能请求或疑问。如果您想贡献代码，请先提交问题，讨论建议的更改。
Add a note to a finding
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| note | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('add') but doesn't cover permissions required, whether notes are editable/deletable, rate limits, or response behavior. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves beyond the basic 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 a single, efficient sentence with zero waste—'Add a note to a finding' is front-loaded and appropriately sized for the tool's apparent simplicity. Every word contributes directly to the core purpose without unnecessary elaboration.
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 an output schema (which handles return values), low complexity (2 simple parameters), and no annotations, the description is minimally complete. It states what the tool does but lacks context on usage, behavioral traits, and parameter details, making it adequate only in a bare-bones sense with clear gaps for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'finding' and 'note' but adds minimal meaning beyond the schema's property names ('finding_id', 'note'). No details on parameter formats, constraints, or examples are provided, failing to adequately clarify semantics for the two required 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 'Add a note to a finding' clearly states the action (add) and target resource (finding), but it's vague about what 'note' entails and doesn't distinguish from sibling tools like 'update_finding_status' or 'create_finding'. It avoids tautology by not just restating the name, but lacks specificity about the note's purpose or format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing finding), exclusions, or compare to siblings like 'update_finding_status' for status changes. The description implies usage but offers no explicit context or decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close an engagement
| Name | Required | Description | Default |
|---|---|---|---|
| engagement_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Close an engagement' implies a mutation, but it does not specify if this is reversible, what permissions are required, or any side effects like data archiving. This leaves critical behavioral traits undisclosed for a tool that likely alters state.
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 extremely concise with a single sentence, 'Close an engagement', which is front-loaded and wastes no words. However, this brevity borders on under-specification, as it omits necessary details, though it is structurally 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?
Given the tool likely performs a mutation (closing an engagement) with no annotations, 0% schema coverage, and an output schema present (which may help), the description is incomplete. It does not address behavioral risks, parameter usage, or differentiation from siblings, failing to provide adequate context for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameter 'engagement_id'. However, it adds no meaning beyond the schema, failing to explain what an engagement ID is, how to obtain it, or its format, leaving the parameter's semantics unclear.
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 'Close an engagement' restates the tool name with minimal expansion, making it tautological. It specifies the verb 'close' and resource 'engagement' but lacks detail on what closing entails or how it differs from siblings like 'update_engagement' or 'get_engagement', leaving the purpose vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'update_engagement' and 'get_engagement', the description does not indicate prerequisites, such as needing an existing engagement, or exclusions, like when not to close an engagement, offering minimal context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new engagement
| Name | Required | Description | Default |
|---|---|---|---|
| branch_tag | No | ||
| build_id | No | ||
| commit_hash | No | ||
| deduplication_on_engagement | No | ||
| description | No | ||
| engagement_type | No | ||
| lead_id | No | ||
| name | Yes | ||
| product_id | Yes | ||
| status | Yes | ||
| tags | No | ||
| target_end | Yes | ||
| target_start | Yes | ||
| version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Create a new engagement' implies a write/mutation operation, but it doesn't describe what happens upon creation (e.g., whether it returns an ID, triggers notifications, or affects other resources), any authentication or permission requirements, rate limits, or error conditions. For a creation tool with 14 parameters and no annotation coverage, this is critically inadequate.
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 extremely concise—a single three-word phrase—with no wasted words. It's front-loaded with the core action ('Create'), though this brevity comes at the cost of completeness. For conciseness alone, it scores perfectly as it says nothing unnecessary, but this doesn't imply quality in other dimensions.
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 complexity (14 parameters, 5 required), lack of annotations, no output schema, and 0% schema description coverage, the description is completely inadequate. It doesn't explain what an engagement is, how to use the tool effectively, what parameters do, or what to expect upon success/failure. For a creation tool in a system with multiple engagement-related siblings, this leaves the agent with insufficient context to operate 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 0%, meaning none of the 14 parameters have descriptions in the schema. The tool description adds no information about what parameters like 'engagement_type', 'deduplication_on_engagement', or 'tags' mean, their expected formats, or how they influence the creation process. With many parameters and zero coverage, the description fails to compensate, leaving the agent to guess at semantics.
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 'Create a new engagement' is a tautology that merely restates the tool name without adding meaningful context. It doesn't specify what an 'engagement' is in this domain, what resources it involves, or how it differs from sibling tools like 'update_engagement' or 'close_engagement'. While it uses a clear verb ('create'), the resource ('engagement') remains undefined and indistinguishable from related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a product_id or lead_id), when to choose 'create_engagement' over 'update_engagement' or 'close_engagement', or any constraints like permissions or timing. With multiple sibling tools for managing engagements, this lack of differentiation is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new finding
| Name | Required | Description | Default |
|---|---|---|---|
| cvssv3 | No | ||
| cwe | No | ||
| description | Yes | ||
| impact | No | ||
| mitigation | No | ||
| severity | Yes | ||
| steps_to_reproduce | No | ||
| test_id | Yes | ||
| title | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers none. It doesn't indicate whether this is a write operation, what permissions are required, whether it's idempotent, what happens on success/failure, or any rate limits. The description fails to add value beyond the implied 'create' action.
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?
While concise with three words, the description is under-specified rather than efficiently informative. It lacks front-loaded critical information and wastes its brevity on stating the obvious. Every sentence should earn its place, but this single phrase adds minimal value beyond the tool name.
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 complexity (9 parameters, 4 required), no annotations, 0% schema coverage, and presence of an output schema, the description is incomplete. It doesn't address the tool's purpose in context, parameter meanings, or behavioral traits, leaving significant gaps for a mutation tool in a security/finding management domain.
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 9 parameters with 0% description coverage, and the tool description provides no parameter information. It doesn't explain what 'cvssv3', 'cwe', 'severity', or other fields mean, their formats, or constraints (e.g., valid severity values). The description fails to compensate for the schema's lack of 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 'Create a new finding' is a tautology that restates the tool name without adding meaningful context. It specifies the verb 'create' and resource 'finding' but lacks specificity about what a 'finding' represents in this domain or how it differs from sibling tools like 'add_finding_note' or 'update_finding_status'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing test_id or engagement), exclusions, or relationships to sibling tools like 'add_finding_note' (for notes on existing findings) or 'update_finding_status' (for modifying findings).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific engagement by ID
| Name | Required | Description | Default |
|---|---|---|---|
| engagement_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It implies a read-only operation ('Get'), but doesn't specify permissions, rate limits, error handling, or what happens if the ID is invalid. For a tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse for an AI 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 the tool's low complexity (one required parameter) and the presence of an output schema, the description is minimally adequate. However, with no annotations and incomplete parameter guidance, it lacks depth for safe and effective use, especially in a context with multiple sibling tools.
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 description mentions 'by ID', which adds context that the single parameter is an engagement identifier, but the schema already defines this as 'engagement_id' of type integer with 0% description coverage. This provides basic semantics but doesn't fully compensate for the lack of schema details, such as ID format or constraints.
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's purpose with a specific verb ('Get') and resource ('engagement by ID'), making it immediately understandable. However, it doesn't differentiate from sibling tools like 'list_engagements' or 'create_engagement', which would require explicit comparison to earn a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'list_engagements' for multiple engagements or 'create_engagement' for new ones, nor does it specify prerequisites like needing a valid engagement ID. This leaves the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get findings with filtering options and pagination support
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| product_name | No | ||
| severity | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions 'filtering options and pagination support' which gives some context about capabilities, but doesn't describe what 'findings' represent in this domain, what permissions are needed, rate limits, error conditions, or what happens when filters return no results. For a tool with 5 parameters and no annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality. It's appropriately sized for what it covers, though it could be more informative. There's no wasted verbiage or unnecessary elaboration.
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 that there's an output schema (which presumably documents return values), the description doesn't need to explain return formats. However, for a tool with 5 parameters, 0% schema description coverage, and no annotations, the description should provide more context about what 'findings' are, how filtering works, and when to use this versus 'search_findings'. The current description is minimally adequate but leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all 5 parameters are undocumented in the schema. The description mentions 'filtering options' which hints at parameters like product_name, severity, and status, but doesn't explain what these filters mean, what values they accept, or their relationships. It also mentions 'pagination support' which hints at limit/offset, but doesn't explain default behaviors or constraints. The description adds minimal value beyond what's obvious from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'findings', making the purpose understandable. However, it doesn't distinguish this tool from its sibling 'search_findings', which appears to serve a similar filtering function. The description is specific about what the tool does but lacks sibling 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?
The description provides no guidance on when to use this tool versus alternatives like 'search_findings' or 'list_engagements'. There's no mention of prerequisites, appropriate contexts, or exclusions. The agent must infer usage from the tool name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List engagements with optional filtering and pagination support
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| name | No | ||
| offset | No | ||
| product_id | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions filtering and pagination support, it doesn't describe important behavioral aspects like whether this is a read-only operation, what authentication is required, rate limits, what happens with invalid filters, or the structure of returned data. The description is minimal and leaves significant behavioral questions unanswered.
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 extremely concise at just 8 words, front-loading the core purpose ('List engagements') followed by key capabilities. Every word earns its place, with no wasted language or redundancy. The structure moves from primary action to supporting features efficiently.
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 that there's an output schema (which handles return values) and no annotations, the description provides the bare minimum for a listing tool. However, for a tool with 5 parameters and 0% schema description coverage, it should do more to explain filtering options and pagination behavior. The description is complete enough to understand the basic purpose but inadequate for optimal tool selection and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 5 parameters, the description provides minimal parameter information. It mentions 'optional filtering and pagination support' which hints at some parameters, but doesn't explain what specific filters are available (name, product_id, status) or how pagination works (limit, offset). The description doesn't adequately compensate for the complete lack of schema 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 clearly states the verb ('List') and resource ('engagements'), making the purpose immediately understandable. It distinguishes from sibling tools like 'get_engagement' (singular) and 'create_engagement' by focusing on listing multiple items. However, it doesn't explicitly differentiate from 'search_findings' or 'list_products' in terms of resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'optional filtering and pagination support' which implies some usage context, but provides no explicit guidance on when to use this tool versus alternatives like 'search_findings' or 'get_engagement'. There's no mention of prerequisites, typical use cases, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all products with optional filtering and pagination support
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| name | No | ||
| offset | No | ||
| prod_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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. While it mentions filtering and pagination support, it doesn't describe important behaviors like whether this is a read-only operation, what permissions are required, rate limits, response format, or what happens when no products match filters. The description is insufficient for a tool with 4 parameters and no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all products') and adds key capabilities. Every word earns its place with no redundancy or unnecessary elaboration.
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 4 parameters with 0% schema coverage and no annotations, but with an output schema present, the description provides basic purpose but lacks sufficient detail about parameter usage, behavioral constraints, and operational context. The output schema reduces the need to describe return values, but the description should do more to compensate for the complete lack of schema descriptions and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'optional filtering and pagination support' which hints at the purpose of some parameters, but doesn't explain what 'prod_type' represents, what format 'name' filtering uses, or the relationship between limit/offset parameters. The description adds minimal value beyond the bare parameter names in 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 verb ('List') and resource ('products'), making the purpose immediately understandable. It distinguishes from siblings by focusing on product listing rather than engagement/finding operations, though it doesn't explicitly contrast with specific product-related alternatives that might exist.
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 'optional filtering and pagination support' which provides some context about when to use parameters, but offers no guidance on when to choose this tool versus alternatives like search_findings or other product-specific tools. No explicit when/when-not statements or sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for findings using a text query with pagination support
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| product_name | No | ||
| query | Yes | ||
| severity | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions 'pagination support' which is useful, but doesn't describe other critical behaviors: authentication requirements, rate limits, error conditions, or what the output contains. For a search tool with 6 parameters, this leaves significant gaps in understanding how it operates.
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 extremely concise at just one sentence with zero wasted words. It's front-loaded with the core purpose and includes key behavioral information (pagination support) efficiently. Every element earns its place without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters with 0% schema description coverage and an output schema exists, the description is moderately complete. The output schema reduces the need to describe return values, but the description still lacks sufficient context about parameter usage, behavioral constraints, and differentiation from siblings. It's adequate but has clear gaps for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only mentions 'text query' and 'pagination support', which partially covers the 'query', 'limit', and 'offset' parameters. However, it doesn't address 'product_name', 'severity', or 'status' parameters at all, leaving half the parameters without semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for findings using a text query with pagination support'. It specifies the verb ('search'), resource ('findings'), and key features (text query, pagination). However, it doesn't explicitly differentiate from sibling tools like 'get_findings' or 'list_engagements', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get_findings' and 'list_engagements' available, there's no indication of when this search tool is preferred over simpler retrieval tools or how it differs in functionality. The mention of 'pagination support' hints at use for large result sets but isn't explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing engagement
| Name | Required | Description | Default |
|---|---|---|---|
| branch_tag | No | ||
| build_id | No | ||
| commit_hash | No | ||
| deduplication_on_engagement | No | ||
| description | No | ||
| engagement_id | Yes | ||
| engagement_type | No | ||
| lead_id | No | ||
| name | No | ||
| status | No | ||
| tags | No | ||
| target_end | No | ||
| target_start | No | ||
| version | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't disclose any behavioral traits such as required permissions, whether changes are reversible, rate limits, or what the response looks like. For a mutation tool with 14 parameters and no annotations, this 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 extremely concise with just four words, front-loaded with the core action. There's no wasted language, though this comes at the cost of completeness. Every word earns its place in conveying the basic 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 complexity (14 parameters, mutation operation, no annotations) and the presence of an output schema, the description is incomplete. It doesn't explain what an 'engagement' is in this context, what fields can be updated, or provide any behavioral context. The output schema helps with return values, but the description should do more for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate by explaining parameters. However, it provides no information about any of the 14 parameters, not even the required 'engagement_id'. This leaves the agent with no semantic understanding of what fields can be updated or their purposes.
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 'Update an existing engagement' clearly states the verb ('update') and resource ('engagement'), but it's vague about what specific aspects of an engagement can be updated. It doesn't distinguish this tool from sibling tools like 'close_engagement' or 'create_engagement' beyond the basic action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing engagement ID), when not to use it (e.g., for creating new engagements), or how it differs from sibling tools like 'close_engagement' or 'create_engagement'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the status of a finding (Active, Verified, False Positive, Mitigated, Inactive)
| Name | Required | Description | Default |
|---|---|---|---|
| finding_id | Yes | ||
| status | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Update' which implies a mutation, but doesn't disclose critical traits: whether this requires specific permissions, if changes are reversible, what happens to associated data, or any rate limits. The description adds minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and lists all status options without unnecessary words. Every element (verb, resource, options) earns its place, making it highly concise and well-structured for quick understanding.
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 a mutation tool with 2 parameters, 0% schema coverage, no annotations, but an output schema exists, the description is minimally adequate. It covers the purpose and status values, but lacks behavioral details (e.g., permissions, side effects) and parameter semantics for 'finding_id'. The output schema reduces the need to explain return values, but more context 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 description coverage is 0%, so the schema provides no parameter descriptions. The description lists the status options, which adds meaning for the 'status' parameter beyond the schema's basic type. However, it doesn't explain 'finding_id' (e.g., how to obtain it) or provide format details for either parameter. It partially compensates for the coverage gap but not fully.
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 'Update' and the resource 'status of a finding', specifying the exact status options (Active, Verified, False Positive, Mitigated, Inactive). It distinguishes from siblings like 'create_finding' or 'get_findings' by focusing on status modification rather than creation or retrieval. However, it doesn't explicitly differentiate from other update tools like 'update_engagement' beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing finding ID), when not to use it (e.g., for other finding attributes), or refer to sibling tools like 'add_finding_note' for related actions. Usage is implied by the action but not explicitly contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_finding_noteclose_engagementcreate_engagementcreate_findingget_engagementget_findingslist_engagementslist_productssearch_findingsupdate_engagementupdate_finding_statusScored across 11 tools
Each tool has a clearly distinct purpose targeting specific resources and actions, such as create_engagement vs. update_engagement, and get_findings vs. search_findings, with no overlapping or ambiguous functions.
All tool names follow a consistent verb_noun pattern using snake_case, such as create_engagement, list_products, and update_finding_status, with no deviations in style or convention.
With 11 tools, the server is well-scoped for defect management, covering key operations like engagements, findings, and products without being overly sparse or bloated.
The tool set provides strong CRUD/lifecycle coverage for engagements and findings, including create, get, update, and list operations, though minor gaps like product creation or deletion might require workarounds.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
