mcp-defectdojo

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v3.3.2
Disambiguation5/5
Each tool targets a distinct entity and action (e.g., product, engagement, test, finding, tags, scans). Detailed descriptions and unique argument sets prevent confusion. No two tools overlap in purpose.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_product, list_findings, close_finding). Even health_check fits the pattern. No mixing of styles or ambiguous verbs.
Tool Count4/5
24 tools is slightly above the ideal range but still reasonable given the breadth of DefectDojo's API (products, engagements, tests, findings, notes, tags, scans). Each tool serves a clear need; no superfluous tools.
Completeness3/5
The toolset covers CRUD for findings and basic operations for products, engagements, and tests. However, missing update endpoints for product and engagement, and no delete operations anywhere, which are notable gaps for full lifecycle management.
Average 4/5 across 24 of 24 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It only mentions write scope and rate limits, but omits key behaviors like auto-creation of product/engagement (auto_create_context defaults true), deduplication, and closing old findings. These are critical for an agent to understand 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loaded with the core purpose. It includes necessary constraints without extraneous information, earning its sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 19 parameters and an output schema, the description fails to provide an overview of the import workflow, return value expectations, or how auto-creation and deduplication integrate. The schema descriptions are detailed but the tool-level context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 tool description does not add any additional meaning beyond what the parameter descriptions already provide. No extra context or examples are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Import' and the resource 'scan report' into 'DefectDojo', leaving no ambiguity about the tool's primary function. It distinguishes from sibling 'reimport_scan' through the verb 'import' vs 'reimport'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions prerequisites ('Requires write scope') and constraints ('Rate-limited'), but does not provide guidance on when to use this tool versus alternatives like 'reimport_scan'. The context for appropriate usage is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond the action: 'Requires write scope' and 'Rate-limited' inform the agent about access and throttling, and 'Returns JSON with created test' clarifies output, compensating for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Reasonably concise: a single sentence followed by a parameter list. The parameter list could be integrated more elegantly, but the description is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists and description mentions it, but missing broader context like prerequisites (e.g., engagement must exist) or side effects, leaving some gaps for a creation tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description lists parameters with some constraints (>0 for integers, YYYY-MM-DD for strings), but does not explain their meaning (e.g., what engagement_id or test_type_id represent), leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new test' with a specific verb and resource. While it distinguishes from sibling tools like create_engagement or create_finding by naming the resource, it does not explicitly differentiate usage scenarios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only states what it does, without providing context for when it should be chosen over other creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions the return format (JSON with items and pagination) but does not disclose read-only behavior, error conditions, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second explains parameters and output. Front-loaded and avoids unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fairly complete for a list operation: explains params, return structure. Lacks info on ordering, filtering, error handling, or authentication needs. Adequate but could be more robust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds meaning by specifying valid ranges for limit (1-100) and offset (>=0), plus defaults. This goes beyond the schema's bare structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List products in DefectDojo', using a specific verb and resource. It distinguishes itself from sibling tools like create_product, get_product, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_findings. No mention of prerequisites, limitations, or pagination strategy beyond basic parameter ranges.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions write scope requirement, rate limiting, and JSON return format, adding moderate behavioral context beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the action, then add essential context. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with output schema present, description covers key behavioral traits and a parameter rule. Minor gaps: no mention of idempotency or error scenarios, but adequate given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description lists all three args and adds a constraint (prod_type_id must be > 0) not present in schema, providing useful semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new product,' which is a specific verb and resource. It differentiates from sibling creation tools only by the resource, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The only contextual note is 'Requires write scope. Rate-limited,' which is behavioral, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden but only states it 'gets' an engagement and returns JSON. It does not mention idempotency, error handling (e.g., what happens if ID doesn't exist), permissions, or side effects. This is minimal disclosure for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, one line for parameters. No redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return structure explanation is unnecessary. However, the description fails to mention error behavior (e.g., returns null or throws on missing ID) or any other completion context. It's minimally viable but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds a constraint not present in the schema: 'engagement_id (must be > 0)'. The schema only specifies integer type with no minimum, so this is valuable. However, it doesn't explain the meaning of the ID (e.g., unique identifier), which is somewhat implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get a single engagement by ID.' It specifies both the verb ('Get') and the resource ('engagement'), and distinguishes it from siblings like 'list_engagements' by indicating it retrieves a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 (e.g., 'list_engagements'). While 'by ID' implies a specific use case, it lacks explicit comparisons or exclusions, making it hard for an agent to decide without prior knowledge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It notes rate-limiting and write scope, and discloses default values for active and verified. However, it does not mention side effects (e.g., duplicate handling) or error conditions, and the return format is vague ('Returns JSON with created finding').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one sentence and a list. It is front-loaded with the purpose. Minor redundancies (listing args both in prose and inline) but overall efficient. Could be more structured with separate sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 4 required, no schema descriptions) and existing output schema, the description covers essential usage: required fields, defaults, return type. Some gaps remain (e.g., response structure, error cases) but adequate for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates by listing all parameters with constraints (e.g., test_id > 0, severity values, defaults). This adds meaning beyond the schema structure, though it could be more detailed (e.g., explaining what test_id references).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new finding') and resource ('a finding'). It lists required arguments, distinguishing it as a creation tool. However, it does not explicitly differentiate from sibling tools like update_finding or close_finding, though the name implies creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions prerequisites ('Requires write scope. Rate-limited.') but provides no guidance on when to use this tool versus alternatives such as add_finding_note or update_finding. No exclusions or explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions return format and arg constraint; does not disclose read-only nature, auth needs, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, essential information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple retrieval tool with output schema; covers purpose, parameter constraint, and return type, but could mention error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema by specifying 'must be > 0' constraint for finding_id, compensating for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get a single finding by ID', uses specific verb and resource, and distinguishes from sibling tools like list_findings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as list_findings or other sibling tools; lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It indicates read-only operation ('Get') and mentions return format, but does not cover authentication needs, error behavior, or missing ID scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences with no filler. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with one parameter and an output schema, the description covers the core purpose, identifier, and return type. It lacks error detail but is otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% based on automated metric, but the description adds the constraint 'must be > 0' for test_id, which is not in the schema. This adds meaningful validation beyond the integer type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'a single test', and the identifier 'by ID'. It distinguishes from list_tests and other get tools by specifying singular retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like list_tests or other get tools. The description only implies usage when a test_id is known, but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers write operation, required scope, rate limits, and return format. However, it omits potential side effects, uniqueness constraints, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and an argument list, front-loading the purpose and avoiding redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a CRUD create tool with output schema, the description adequately covers input format and return type, though missing error handling details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are listed with type hints and format constraints (e.g., 'product_id (> 0)', 'YYYY-MM-DD'), compensating for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new engagement') and resource, distinguishing it from sibling tools like create_finding or create_product. It provides specific argument details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions write scope and rate limits, but does not clarify when to use this tool over alternatives 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, permissions, or side effects beyond the obvious listing operation. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first for purpose, second for parameters and return structure. No extraneous words, front-loaded, and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers return structure and parameter constraints. However, it omits details like default ordering or filtering capabilities, which would enhance completeness for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the tool description adds essential meaning by specifying constraints: product_id > 0, limit 1-100 (default 20), offset >= 0. This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List engagements for a product,' which uses a specific verb and resource, and distinguishes it from siblings like 'get_engagement' or 'create_engagement.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter constraints but does not explicitly state when to use this tool versus alternatives or mention any prerequisites or exclusions. It gives context but lacks guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so full burden falls on description. It describes return structure but lacks details on error behavior, authorization needs, or what happens if engagement_id does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second lists arguments and return structure. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, parameters, and return format. Minor gaps in error handling and edge cases, but overall sufficient for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 0%, the description adds meaningful constraints and validations (e.g., engagement_id > 0, limit 1-100, offset >= 0) for all three parameters, exceeding what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'tests for an engagement', directly differentiating it from sibling tools like list_engagements or list_findings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Parameter constraints (engagement_id > 0, limit 1-100, offset >= 0) and defaults are given, but no explicit when-to-use or when-not-to-use guidance versus alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially compensates by describing the return format and noting that note entries are 'F-002 wrapped.' However, it does not disclose potential side effects, authentication needs, or confirm read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, first stating purpose, then detailing arguments and return format. No filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description specifies the return envelope structure and note entry format. Since an output schema exists, it is acceptable. It does not mention pagination details but the envelope includes pagination, so it's implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly states 'finding_id (> 0)', adding validation and meaning that the schema lacks. This compensates for zero schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List notes for a finding,' which is a specific verb and resource. It differentiates from sibling tools like list_findings by specifying notes for a finding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching notes but does not provide explicit guidance on when to use this tool versus alternatives like add_finding_notes. It lacks exclusion criteria or context for optimal use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description explains the return format ('items' and 'pagination') and includes a historical note about the has_jira parameter. However, it does not disclose rate limits, auth needs, or default sorting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and parameter summary. It is fairly concise given the 17 parameters, though the DOM-19 note on has_jira is slightly tangential for a typical user.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and high parameter count, the description covers all filter semantics and return structure. It addresses the complexity well, but lacks guidance on pagination default or total count.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
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 details each parameter with types, constraints (e.g., '>0' for IDs, '1-100' for limit), allowed values for severity, and defaults. This adds significant meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List findings with optional filters,' which is a specific verb (list) and resource (findings). It distinguishes from siblings like get_finding (single) and create_finding (write operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists filters but does not explicitly guide when to use this tool versus alternatives like get_finding for a single finding or list_tests for tests. The usage context is implied but not contrasted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description adds 'Requires write scope' and 'Rate-limited', but doesn't disclose other behaviors like impact on existing findings, which is covered by parameters but not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 21 parameters and output schema, the description covers the core action but misses some nuance about the reimport process (e.g., updating vs overwriting). Still mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds no extra parameter meaning beyond the schema definitions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (re-import), the resource (scan report into existing test), and the context (DefectDojo). It is specific enough to distinguish from import_scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It indicates when to use (re-import into existing test) and prerequisites (write scope, rate-limit), but doesn't explicitly state when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses write scope and rate-limiting but lacks details on error handling or behavior when inputs are invalid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no redundancy. Purpose first, then conditions, then arguments, then return. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (mentioned 'Returns JSON with tags array'), the description is adequate for a simple tool, though it lacks error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning: 'finding_id (> 0)' and 'tags (non-empty list of tag strings to remove),' clarifying constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Remove tags from a finding,' clearly specifying the verb and resource. It distinguishes itself from sibling tools like add_finding_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions 'Requires write scope' and 'Rate-limited,' providing context but no explicit guidance on when to use vs alternatives like update_finding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It implies a safe read operation and specifies return fields, but doesn't disclose error handling, authentication, or rate limits. Adequate for a simple get.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two crisp sentences that front-load the purpose, then provide parameter details and output structure. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameter constraint, and return fields. Missing error conditions or special cases, but output schema existence reduces the burden. Complete enough for a straightforward fetch.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description adds constraint 'product_id (must be > 0)' and lists return fields, adding meaningful context beyond the bare integer type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single product by ID,' using a specific verb and resource. It distinguishes from sibling tools like 'get_engagement' or 'list_products'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (to retrieve a single product by ID) and implies context for alternatives like listing. However, no explicit when-not-to-use or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses rate limiting, write scope requirement, and a detailed state-transition gate that explains rejection and redirection behavior. This is thorough, though it could mention the exact error response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs, first immediately stating the update action and listing fields, second detailing the state gate. It is clear and without filler, though the second paragraph is fairly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately covers the update behavior and the complex state-transition gate. It mentions the return format. One minor gap: no mention of error responses beyond redirection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description must compensate. It lists all optional parameters and notes severity enum values (Critical/High/Medium/Low/Info) and that finding_id must be >0. However, for many self-explanatory fields, it adds minimal meaning beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing finding' and lists the fields that can be updated. It also distinguishes from sibling tools like 'reopen_finding' by detailing when that alternative should be used, thanks to the state-transition gate explanation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states requirements such as 'At least one field required' and 'Requires write scope. Rate-limited.' It also provides clear when-not guidance: state-transition gate conditions that redirect to 'reopen_finding', with role-based exceptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description clarifies it's a read/list operation (no side effects) and describes return format (items array with pagination). Does not address auth or rate limits, but sufficient for a safe list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences covering purpose, usage, and parameters/returns. No waste, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers purpose, parameters, and return format. Output schema exists so full return documentation not needed; description mentions items and pagination sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds constraints beyond schema: limit 1-100 with default 20, offset >= 0. Compensates for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it lists product types in DefectDojo and distinguishes from sibling tools like list_products by clarifying it's for product types, not products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage scenario: finding valid prod_type_id for create_product. Does not mention when not to use or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses authentication requirements (write scope), rate limiting, and return type. It also provides argument constraints. However, it does not specify whether tags are appended or replaced, which could be considered a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that efficiently convey purpose, constraints, and behavioral traits. No unnecessary words; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and an output schema, the description covers input constraints, authorization, rate limits, and return type. It is complete given the tool's complexity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description must compensate. It adds constraints: finding_id > 0, tags non-empty list with each string <= 200 chars. These are not present in the schema, adding significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add tags to a finding' with a specific verb and resource. The sibling tool 'remove_finding_tags' makes it easy to distinguish, as this tool adds while the sibling removes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context: requires write scope and is rate-limited. It does not explicitly state when to use versus alternatives, but the sibling tool names and the description's clarity imply appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. It specifies the return format (JSON with status 'ok' or 'unhealthy' and a message), which adequately discloses behavior for a read-only connectivity test.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no extraneous words. Front-loaded with verb and resource. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, simple output schema, and no annotations required, the description fully covers the tool's purpose and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters to document (schema coverage 100%). Description adds no additional parameter info but is unnecessary given the tool's simplicity. Baseline is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks connectivity to the DefectDojo instance using a specific verb and resource. Unambiguous and distinct from sibling tools which operate on specific entities like findings or products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the use case (check connectivity). While no alternatives or exclusions are mentioned, the context is clear given the tool is a simple health check with no overlapping siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It discloses pagination behavior (limit range 1-100, offset >= 0 with defaults) and return format (JSON with items array and pagination metadata). It implies a read-only operation, though not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences. It front-loads purpose, then usage guidance, then parameter details and return format. Every sentence is efficient and contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers purpose, usage context, parameter constraints, and return structure. It is complete for a list tool, especially with an implied output schema providing further details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds value by specifying valid ranges (limit 1-100, offset >= 0) and defaults (20 and 0), which the schema lacks. This compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists test types in DefectDojo and explicitly connects to the sibling tool create_test for finding valid test_type_id values, making its purpose and resource well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance by stating 'Use this to find valid test_type_id values for create_test,' indicating when to use it. However, it does not mention when not to use it or alternatives, but the context is clear given the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: required permission, rate-limiting, and a detailed edge case on partial failure (note attachment fails while reopen succeeds), including response structure and audit events.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and permission. Includes a detailed edge-case section that adds value but slightly lengthens description. Well-structured overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given sibling tools, parameter count, and presence of output schema, the description covers all necessary aspects: purpose, usage, parameters, behavior, and edge cases. No gaps evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains finding_id must be >0 and note is optional with purpose 'reason for reopening'. Could add format constraints but provides sufficient meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reopens a previously mitigated finding. Differentiates from siblings like close_finding and update_finding by specifying the action and permission gating (engagement_mgmt vs finding_mgmt).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States when to use: reopening a mitigated finding. Notes permission requirements and that it signals remediation failure. Does not explicitly mention alternatives like add_finding_note for just adding a note, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: authentication requirement (write scope), rate limiting, and the return value wrapping behavior (F-002 wrapped entry). It also references the environment variable to disable wrapping and a design document, providing comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at around 4 sentences, with the main purpose stated first. It includes useful but non-essential details (like DEC-027 reference). Could be slightly more streamlined, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, no annotations, rich output schema), the description covers purpose, usage context, parameter constraints, and return value specifics. It complements the output schema by explaining the wrapping behavior, making it complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds critical parameter details: finding_id must be >0, entry is note text, private defaults to false. It also explains the return value's entry field wrapping, which goes beyond the schema. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a note to a finding.', which is a specific verb+resource combination. It is distinct from sibling tools like add_finding_tags or close_finding, and the context of write scope and rate limiting further clarifies the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions prerequisites ('Requires write scope') and rate limiting, giving clear usage context. However, it does not explicitly state when not to use this tool or provide alternatives among siblings, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: it mentions write scope, rate limits, and a detailed partial failure mode for note attachment, including the _warning field and audit event. Returns JSON with updated finding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with key information. However, the DOM-21 block is lengthy and technical, potentially excessive for quick reference, but still valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage constraints, parameter details, return type, and error behavior thoroughly. Given the lack of annotations and output schema, it provides complete context for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds constraints not present in the input schema: finding_id > 0, reason enum values (mitigated/false_positive/out_of_scope/duplicate), and note optionality. This significantly clarifies parameter use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool closes a finding with a reason, clearly identifying the action and resource. It effectively differentiates from sibling tools like 'reopen_finding' by focusing on closure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states prerequisites: write scope required and rate limits. It lists valid reasons for closing. However, it does not explicitly instruct when to use this tool over alternatives like 'update_finding' or 'reopen_finding'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-defectdojo MCP server](https://glama.ai/mcp/servers/inspicere/mcp-defectdojo/badges/card.svg)](https://glama.ai/mcp/servers/inspicere/mcp-defectdojo)

Score Badge

Copy to your README.md:

[![mcp-defectdojo MCP server](https://glama.ai/mcp/servers/inspicere/mcp-defectdojo/badges/score.svg)](https://glama.ai/mcp/servers/inspicere/mcp-defectdojo)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/inspicere/mcp-defectdojo'

If you have feedback or need assistance with the MCP directory API, please join our Discord server