GuardianShield

by sparkvibe-io

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

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

Latest release: v1.2.1
Disambiguation3/5
Several scan tools overlap in purpose: scan_file, scan_code, scan_directory, scan_files, and check_secrets all detect vulnerabilities and secrets. scan_input and scan_output are distinct, but the boundaries between the code scanning tools are blurry, potentially causing selection errors.
Naming Consistency4/5
Most tools follow a consistent verb_noun pattern with underscores. A few deviate with prepositions (scan_with_baseline) but overall the naming is predictable and readable.
Tool Count3/5
With 27 tools, the server is feature-rich but borderline heavy. Each tool serves a distinct function for code analysis, dependency checking, and security management, but the count is slightly above the ideal range for ease of agent navigation.
Completeness4/5
The tool set covers nearly all aspects of security scanning: static analysis, input/output checking, dependency scanning, false positive management, baselines, quality gates, and export. Missing advanced features like custom profile creation or result deletion, but these are minor gaps.
Average 3.6/5 across 27 of 27 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 2 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on March 3, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
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.
This repository includes a glama.json configuration file.
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 provided, the description bears full responsibility for behavioral disclosure. It mentions using an external database (OSV.dev) but does not state side effects, rate limits, permissions, or whether the operation is read-only. The output format is also unspecified, leaving behavioral traits largely hidden.
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 sentences, each with a distinct purpose: stating the action and describing the input. It is efficient with no wasted words, though it omits important details. It earns a high score for brevity and front-loading core purpose.
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?
Given the tool has a single parameter with schema description, but no output schema and no annotations, the description should compensate by detailing the return format, side effects, and relationship to sibling tools. It fails to do so, leaving the agent uncertain about output and behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'dependencies' array with name, version, and ecosystem (including 'Go' and 'Packagist'). The description adds little meaning and is misleading by restricting ecosystems to 'PyPI or npm', contradicting the schema. It does not explain valid values or format beyond what the schema provides.
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 it checks package dependencies for vulnerabilities using the OSV.dev database, which is a specific verb+resource combination. However, it does not differentiate from the sibling tool 'scan_dependencies' which may also check dependencies, and the phrase 'Provide a list of packages...' could be interpreted as describing the input rather than the output, causing slight ambiguity.
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 is given on when to use this tool versus alternatives like 'scan_dependencies' or 'scan_file'. The description does not mention context, prerequisites, or exclusions, leaving the agent without decision support.
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 the description carries the full burden for behavioral disclosure. The description mentions 'active for the current session,' hinting at session-scoped state mutation but does not clarify if the change is persistent, reversible, or what happens to previously enabled engines. It lacks crucial details like whether it overwrites or merges with existing settings, required permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, no filler or redundancy. It is front-loaded with the primary action and scopes the functionality. One sentence could be trimmed if schema already covers the parameter, but overall efficient.
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?
Given the absence of annotations and output schema, and the existence of many sibling tools (like set_profile, scan_code, check_secrets) for which interaction is unclear, the description is incomplete. It does not explain the return value (success/failure), error conditions, or how session scoping works. A mutation tool with one parameter should provide more context about effects and boundaries.
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% with a single parameter documented as 'List of engine names to enable.' The description adds minimal value by restating this as 'list of engine names' and referencing list_engines for discovery. With complete schema coverage, a baseline of 3 is appropriate since the description adds only marginal context beyond the schema.
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 tool sets which analysis engines are active for code scanning, using a specific verb ('Set') and resource ('analysis engines'). It distinguishes itself from siblings like list_engines by noting that available engines can be listed with that tool. However, it could be slightly more explicit about the scope of the session.
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 by indicating it accepts a list of engine names to enable, and references list_engines as a companion tool. However, it provides no guidance on when to use this versus alternatives like set_profile, check_secrets, or other scanning tools. It does not specify prerequisites, error conditions, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It reveals that the finding will be flagged in future scans and that similar patterns elsewhere will be annotated—both critical side effects. However, it does not clarify whether the action is reversible (though a sibling `unmark` exists), what constitutes 'similar patterns,' or any permission requirements. This is adequate but leaves gaps.
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 sentences, front-loaded with the core action, and every word adds value. It is concise but could be slightly more structured (e.g., a separate bullet for side effects). Still, no fluff is present.
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?
For a mutation tool with no output schema and no annotations, the description covers the main action and key side effects (future scans, pattern annotation). However, it does not describe the return value, error cases, or how to obtain the `finding` object. The required input constraint (finding must be a dict from a scan tool) is in the schema but not echoed. Overall it is acceptable but not thorough.
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% (both `finding` and `reason` have descriptions). The description adds no parameter-specific information beyond what the schema already provides. The baseline for full schema coverage is 3, which is appropriate here.
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 verb and resource: 'Mark a security finding as a false positive.' It also explains the effect on future scans and similar patterns, which adds specificity. However, it does not explicitly distinguish from the sibling `unmark_false_positive` or `list_false_positives`, leaving some ambiguity about the exact scope.
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 is given on when to use this tool versus alternatives. For instance, the description omits any mention of `unmark_false_positive` for reversing the action or `list_false_positives` for reviewing existing marks. The statement about 'similar patterns' implies a broader impact but doesn't explain when this automated propagation is undesirable.
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 description carries full burden. It only says 'returns recent scan events' without specifying ordering, recency definition, pagination, or auth requirements. Minimal behavioral 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?
Single sentence with clear subject, verb, and object. No redundant words. Efficiently communicates the tool's purpose.
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?
For a simple query tool with 2 optional params and no output schema, the description is adequate but lacks details on default behavior (e.g., sort order, definition of 'recent'). Gaps exist but are not critical.
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 coverage is 100% with descriptions for both parameters (limit and scan_type). Description adds no extra parameter meaning beyond the schema, so baseline score of 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?
Description clearly states 'Query the security audit log' with specific verb and resource, and lists return fields (timestamps, scan types, finding counts, input hashes). This distinguishes it from sibling scan tools that perform scans rather than query logs.
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 such as get_findings or specific scan tools. No conditions, exclusions, or prerequisites mentioned, leaving the agent to infer usage context.
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 (no readOnlyHint, destructiveHint, etc.), so the description must carry all behavioral disclosure. It only states 'scan multiple files' and output structure, but does not specify the type of scan (e.g., security, secrets, code quality) or any side effects, permissions, or rate limits. This is insufficient for a tool with many scanning siblings.
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, no fluff. The purpose and output structure are front-loaded. However, it could be structured to include a quick usage condition without adding length.
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?
Given the rich sibling context (23 tools including scan_file, scan_code, check_secrets, etc.) and the absence of annotations or output schema, the description falls short. It doesn't specify what type of scanning is performed or how findings relate to those from sibling tools, leaving significant gaps for an agent to decide when to invoke it.
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 coverage is 100% (both 'path' and 'language' have descriptions). The description adds no additional meaning beyond the schema's own documentation—e.g., it doesn't explain how 'language' hint affects scanning or how grouping by file works. Baseline score of 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 tool scans multiple files in one call and describes expected output (findings grouped by file with a summary). This directly addresses the sibling tool 'scan_file' by explicitly targeting multiple files, differentiating it effectively.
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 use for scanning multiple files at once, and the sibling list includes 'scan_file' for single files, but no explicit 'when to use' or 'when not to use' guidance is provided. Context is implied rather than stated, leaving the agent to infer alternatives.
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 provided, the description carries full burden. It only states 'list' and 'optional filtering', but does not disclose behavioral traits such as authentication needs, rate limits, pagination behavior, or whether the operation is read-only (though implied). This is insufficient for a tool lacking any annotation safety signals.
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 sentences and brief, but the second sentence ('Shows findings that have been marked as false positives') is slightly redundant with the first. Still, it is front-loaded and concise overall.
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 tool's simplicity (2 optional parameters, no output schema), the description covers the core purpose. However, it lacks details about return format, pagination handling (though limit hints at it), and context like scope of records (e.g., per project or global). For a tool without output schema, more completeness would be beneficial.
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?
Input schema has 100% description coverage for both parameters (limit, scanner). The description repeats 'optional filtering by scanner' but adds no new meaning beyond the schema. Baseline score 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 states 'List active false positive records', which is a specific verb+resource pair. It distinguishes this tool from siblings like mark_false_positive (create) and get_findings (all findings) by focusing solely on false positive records.
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 viewing false positive records but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though sibling names offer implicit contrast.
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 carries the burden. It explains that format is auto-detected from the filename, which is a behavioral trait, but does not disclose error handling behavior (e.g., unsupported format, malformed content), or whether the tool is read-only. Since no annotations exist, the description should clarify more, but it does provide some 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 a single sentence plus a list of supported formats. It is concise and front-loaded with the main purpose. The list is necessary because it clarifies what 'dependency manifest' covers. No unnecessary words.
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?
The tool has only two simple parameters with full schema coverage, and no output schema, so the description need not explain return values. However, since there are no annotations, it could have provided more context on what 'structured list' looks like, or what happens with unsupported formats, making it slightly incomplete for a tool with no output schema.
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 the schema already describes both parameters why they are needed. The description adds that 'filename' is used for format detection and that 'content' is the file contents, but the schema already states that. The description's list of supported formats is useful but not essential for understanding each parameter.
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 tool parses a dependency manifest file into a structured list of dependencies, with a specific verb and resource. It also lists supported formats, though it doesn't explicitly contrast with sibling tools like scan_dependencies or check_dependencies, which might overlap.
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 (when you have a manifest file content and filename), and the supported formats list gives context. However, it doesn't explicitly state when to use this tool vs. alternatives like scan_dependencies or check_dependencies, nor does it mention any exclusions or prerequisites.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the tool scans for security vulnerabilities and secrets and returns findings with severity, type, and remediation guidance. However, it does not disclose important behavioral traits such as whether the scan is static or dynamic, if the code is executed, network calls are made, or if the tool has any rate limits, performance impacts, or prerequisites. The description is adequate but leaves open questions about safety and performance.
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 a concise two-sentence structure that front-loads the tool's primary purpose. It lists specific vulnerability types to set context and mentions the return format. It is efficient and does not contain filler, earning a high score, though it could be slightly improved by adding a brief usage hint.
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 tool's complexity (4 parameters, no output schema), the description provides the core purpose and return format but lacks details on behavior, parameter semantics, and usage context compared to siblings. With 26 sibling tools, more explicit differentiation would strengthen completeness. The description is functional but not comprehensive.
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 the baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides. For example, it does not clarify how the 'engines' parameter interacts with the tool, what valid values for 'language' are, or how 'file_path' influences the scan. The description adds no extra semantic value for parameters.
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 'Scan source code for security vulnerabilities...' and lists specific vulnerability types (SQL injection, XSS, etc.) as well as hardcoded secrets. It also mentions the return type, which helps distinguish it from sibling tools like scan_file or scan_directory that may focus on scanning a single file or a directory rather than arbitrary code content.
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 the tool is meant for scanning source code for vulnerabilities and secrets, but does not explicitly state when to use it versus alternatives like scan_file (for a single file), scan_directory (for a directory), or check_secrets (for secrets only). No guidance is given on when not to use it, such as when scanning compiled code or non-source artifacts.
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 the description bears full responsibility for behavioral disclosure. It mentions that 'All matched secrets are redacted in findings,' which is a useful behavioral trait. However, it does not state whether the tool is read-only, whether it modifies the input, requires authentication, has rate limits, or what the side effects of redaction are. For a tool with no annotations, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, straight to the point, and front-loaded with the purpose. Every word adds value: 'Dedicated secret and credential detection' sets the context, the list of secret types provides specificity, and the final sentence on redaction adds a critical behavioral note. There is no redundancy or fluff.
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 tool's simplicity (2 parameters, no output schema, no nested objects), the description covers the core functionality and one behavioral detail (redaction). However, it does not describe the return format ('findings') or error conditions. The tool's complexity is low, but without an output schema, the description should at least hint at what the output looks like. It is minimally adequate but not comprehensive.
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 coverage is 100%: both parameters ('text' and 'file_path') have descriptions in the input schema. The tool description does not add any additional meaning beyond the schema. For example, it does not explain how 'file_path' is used for context or how the 'text' parameter handles large inputs. Baseline 3 is appropriate since the schema already documents the parameters adequately.
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 it is a 'Dedicated secret and credential detection' tool that 'scans text' for a comprehensive list of secret types. The verb 'scans' and resource 'text' are specific, and the list of secret formats (AWS keys, GitHub tokens, etc.) clarifies the scope. It distinguishes itself from siblings like 'scan_file' or 'scan_input' by being specialized for secrets.
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 this tool should be used for secret detection by labeling it as 'dedicated,' but it does not explicitly state when to use it versus alternatives (e.g., scan_file, scan_code). No guidance is provided on when not to use it or what prerequisites (e.g., no redaction toggle) exist. The context is clear but lacks exclusions or comparison.
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 (readOnlyHint, destructiveHint, etc.), so the description carries the full burden of behavioral disclosure. The description does not mention whether this operation is read-only or destructive, whether it requires prior scans, or how the export handles large code inputs. Given the lack of annotations and no behavioral details, a score of 2 is warranted.
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 a single, well-structured sentence that front-loads the core purpose and lists relevant integrations. Every word earns its place without redundancy. It is concise and easily scannable.
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 4 parameters (2 required), no output schema, and no annotations, the description is somewhat complete but has gaps. It explains the output format and use cases but does not mention what happens on failure, rate limits, or whether the tool validates engines against available ones. A score of 3 reflects adequate but not thorough coverage.
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 all four parameters have descriptions in the schema. The description adds no further parameter details beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting, and the description does not augment it.
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 uses specific verb 'Export' and resource 'scan findings as SARIF 2.1.0', clearly stating the output format and use cases (GitHub Code Scanning, VS Code, CI integration). It distinguishes from sibling tools (like scan_file, scan_code) which focus on scanning rather than exporting results in a standardized format.
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 exporting findings to SARIF format, but does not specify when to use this tool versus alternatives like get_findings (which might return findings in a different format) or scan_* tools. No explicit when-not-to-use or prerequisites are mentioned. A score of 3 is appropriate because the context is clear but lacks actionable guidance.
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 must disclose behavioral traits. It mentions recursive scanning, filtering, and progress reporting, adding value. However, it does not state whether the tool is read-only, if it requires network access, or if it could be destructive (e.g., modifying files). The safety profile is not explicit.
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 two sentences covering purpose, features, and output. Every sentence contributes information without redundancy. It is appropriately sized and front-loaded with the primary action.
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 tool has 3 parameters, no output schema, and no annotations, the description covers purpose, supported features, and return scope. However, it lacks details on error handling, performance implications (e.g., large directories), and return format. The description is adequate but not fully complete for a production tool.
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 coverage is 100%, so the schema already documents each parameter. The description summarizes the parameters ('extension filtering, exclude patterns') but does not add new meaning beyond what is in the schema. According to the guidelines, baseline is 3 when coverage is high, and the description does not significantly enhance understanding.
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 recursively scans a directory for vulnerabilities and secrets. It distinguishes from siblings like scan_file (single file) and scan_diff (diff) by specifying the resource as a directory. The verb+resource combination is specific and 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 is provided on when to use this tool versus alternatives such as scan_file, scan_files, or scan_diff. The description does not mention prerequisites, exclusions, or when not to use it, leaving the agent without context for selection.
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 are provided, so the description carries the full burden. It discloses the return format (line numbers, severity, CWE IDs, remediation) and auto-detection of language. However, it does not mention side effects (e.g., read-only nature), file size limits, supported file types, or whether network access is required. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The purpose is front-loaded, and every sentence adds essential information. Excellent conciseness.
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 tool with no output schema and few parameters, the description covers what the tool does, how it detects language, and what it returns. It is mostly complete, but could be improved by mentioning file size limits or supported file types to fully address the scanning context.
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?
Input schema covers both parameters with 100% description. The description adds value by explaining auto-detection of language from file extension and the optional nature of the language hint, which provides context beyond the schema's property descriptions.
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 tool scans a single source file for vulnerabilities and secrets, with auto-detection of language. It specifies the return contents (line numbers, severity, CWE IDs, remediation). However, it does not explicitly differentiate from sibling tools like scan_input or scan_code, leaving some ambiguity.
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 explicit guidance on when to use this tool vs alternatives. The description only implies it is for single files, but does not mention when not to use it (e.g., for directories, use scan_directory) or provide any prerequisites.
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 are provided, so the description must fully convey behavior. It correctly indicates a read-only retrieval operation. However, it omits details about pagination, ordering, default filter behavior (returns all findings?), and any rate limits or data freshness considerations.
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?
Single sentence of 16 words, front-loaded with the action and resource. No redundant phrases. Every word contributes meaning.
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?
No output schema is provided, but the description does not mention the return format (e.g., list of finding objects with certain fields). Also lacks information on default limit behavior (schema says default 100, but description does not surface this). Given the simplicity of a filtered retrieval tool, the description is adequate but not fully 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?
Schema coverage is 100% and includes descriptions for all parameters. The description adds only a summarizing list of filter fields, which is useful but does not provide additional meaning beyond what the schema already offers. 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 verb 'Retrieve' and resource 'past security findings from the audit database', and lists the optional filter dimensions (type, severity, audit ID). This distinguishes it from sibling tools like 'scan_file' which perform active scanning rather than querying historical records.
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 the tool is for querying past findings with filters but provides no explicit guidance on when to prefer this over siblings such as 'audit_log' or 'list_false_positives'. No when-not-to-use or alternative recommendations are given.
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 the description must fully disclose behavioral traits. It only states the tool 'gets' configuration, but does not mention whether it is safe, requires authentication, has side effects, or any rate limits. Critical behavioral context is missing.
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 a single, concise sentence (12 words) that is front-loaded with the core action. Every word is necessary; no superfluous information.
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?
The tool has no parameters, no output schema, and no annotations. The description tells what the tool does but does not elaborate on the structure or format of the returned configuration. It is adequate for a simple get operation but lacks thoroughness.
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?
There are zero parameters, and the schema coverage is 100%. Per guidelines, the baseline is 4. The description adds value by specifying what the tool returns ('scanner settings and blocked content categories'), which goes beyond the empty 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 clearly states the tool retrieves the current safety profile configuration, specifying 'scanner settings and blocked content categories'. It uses a specific verb ('get') and resource ('profile'), distinguishing it from write tools like 'set_profile'.
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 this is a read operation but provides no explicit guidance on when to use it versus alternatives (e.g., 'shield_status' or 'audit_log'). It does not mention prerequisites or exclusions, making it minimally adequate.
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 mentions recursive scanning and external database lookup (OSV.dev) but fails to state whether network access is required, whether the operation is read-only, or how failures are handled. Important behavioral details are missing for an agent to safely invoke the tool.
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?
A single sentence that efficiently conveys the tool's full functionality. Every clause adds value (scan type, target files, actions, data source). No redundancy or filler.
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?
The description covers core function but omits output format (no output schema provided) and important behavioral context like network requirements or error behavior. For a tool with many siblings, it lacks explicit differentiation and return value description.
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 100% with each parameter having a brief description. The description adds meaning by explaining the overall purpose (vulnerability checking) and listing concrete manifest file examples, which helps an agent understand the tool's context beyond raw 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 the action (recursively scan), resource (directory for manifest/lockfiles), and outcome (parse dependencies and check for known vulnerabilities using OSV.dev). It lists specific manifest files, making the tool's scope precise and distinguishing it from sibling tools like scan_file or scan_code.
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?
No explicit guidance on when to use this tool vs. alternatives (e.g., check_dependencies, scan_directory). The description implies its use for dependency vulnerability scanning but does not provide exclusions or compare with siblings. Usage context is inferred but not clearly laid out.
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 the description carries the full burden of behavioral disclosure. It states the tool returns only new findings, which is a key behavioral trait. However, it does not disclose whether the tool is read-only, what happens if the baseline file is missing, or if the findings are saved or persisted. Important behaviors are omitted.
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 two sentences, front-loaded with the primary action and result. Every word contributes to understanding the tool's purpose and prerequisite. No redundancy or filler.
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 four parameters, no output schema, and no annotations, the description provides enough context for the core functionality but leaves gaps. It does not explain the output format beyond 'new findings', nor does it address error cases (e.g., missing baseline) or update behavior. It is adequate but not thorough.
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 coverage is 100%, so all parameters are documented in the schema. The description adds minimal parameter-specific meaning: it references the baseline concept (relevant to baseline_path) and implies the 'code' parameter is the input. It does not add substantial value beyond the schema, meeting the baseline expectation of 3.
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 uses a specific verb ('scan') and resource ('code') with a clear differentiator: 'compare against a saved baseline, returning only NEW findings'. This distinguishes it from sibling tools like scan_code, scan_file, and scan_directory, which do not mention baseline comparison.
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 explicitly states a prerequisite: 'Use save_baseline first to create a baseline.' This provides clear context for when to use this tool. However, it does not explicitly mention when not to use it or suggest alternatives, though the purpose implies it is for incremental scanning.
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 present, so the description must fully disclose behavioral traits. It mentions that profiles adjust sensitivity and blocked categories, but omits side effects like whether the change persists across sessions, if it requires special permissions, or if it is reversible. This is insufficient for a mutation tool.
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 two concise sentences with no redundant information. The first sentence states the action, the second explains the profiles and their effect. 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?
The tool is simple (1 parameter, no output schema). The description covers what it does and the meaning of the profiles. However, it does not mention the return value (e.g., confirmation message or new profile status), which would be helpful for completeness given the lack 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 input schema has 100% coverage (the parameter 'name' has a description), providing a baseline of 3. The tool description adds value by explaining that each profile adjusts scanner sensitivity and blocked categories, giving semantic meaning beyond the enum labels.
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 uses a clear verb ('Switch') and specific resource ('safety profile'), and lists all available values. It distinguishes the tool from siblings like 'get_profile' (which reads the current profile) and 'set_engine' (which configures a different aspect).
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 states the tool's purpose but provides no explicit guidance on when to use it versus alternatives (e.g., 'get_profile' for viewing, or when a profile change is needed before scanning). The use case is implied but not spelled out.
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 the description must fully convey behavioral traits. It states 'sync' and 'update the cache', implying a write operation, but does not disclose side effects, permissions required, rate limits, or whether the operation is idempotent. The optional 'packages' parameter's effect on behavior (e.g., omitting it syncs all packages) is not explained.
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 efficient sentences: first defines purpose, second provides usage context. No unnecessary words or repetition. Front-loaded with the core action.
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?
With no output schema and no annotations, the description should compensate by clarifying return values, error states, and full scope of the sync operation. It covers the basic need but lacks detail on what the agent can expect after calling this tool, especially for error handling or partial sync behavior.
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 the description adds no significant meaning beyond the schema. The schema already describes both parameters adequately (ecosystem with enum, packages as optional array). The description does not clarify behavior when packages is omitted, but the baseline score of 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 ('Sync') and the resource ('local OSV vulnerability database for a given ecosystem'). It distinguishes from sibling tools like 'check_dependencies' and 'scan_dependencies' by focusing on cache update rather than analysis.
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 second sentence explicitly advises calling this before checking dependencies, providing clear usage context. However, it does not mention when not to use or alternative approaches, which would improve guidance further.
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 are provided, so the description must fully convey behavioral traits. It discloses that the tool returns engine details and notes the 'enabled in the current profile' aspect, which is helpful. However, it does not mention whether authentication is required, if results are cached, or if there are any side effects (though listing is inherently read-only). The description provides adequate but not exhaustive 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 concise sentences that front-load the core action ('List available analysis engines...') and then specify the return details. Every word serves a purpose, with no redundancy or fluff.
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 zero parameters and no output schema, the description covers the essential information: what the tool lists and the fields returned. It could be more complete by mentioning whether the list is filtered by the current profile or includes all engines system-wide, but the phrase 'whether it is enabled in the current profile' subtly implies all engines are listed with profile-specific status. Slight gap: no mention of required prerequisites like having a profile set.
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 input schema has no parameters, so schema coverage is 100%. The description adds no parameter-specific information because none is needed. Baseline score of 3 applies as the description neither adds nor suffers from parameter gaps.
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 uses the specific verb 'list' with the resource 'analysis engines', and clarifies it returns name, enabled status, and capabilities. This clearly distinguishes it from sibling tools like set_engine, scan_file, or list_false_positives, which have different purposes.
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 does not explicitly state when to use this tool versus alternatives. However, given the tool takes no parameters and is a simple list, the usage context is implied (e.g., to view available engines before enabling or using one). No exclusion criteria or alternative tools are mentioned.
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 the description carries the full burden. It lists the types of injection detected, but it does not disclose what happens upon detection (e.g., return value, error, or modification), nor does it state whether the tool is read-only, has side effects, or requires special permissions. The behavioral description is incomplete for a security-checking tool.
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 two sentences with no wasted words. The first sentence states the core action, and the second enumerates the detection categories. It is 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 tool has only one parameter and no output schema, the description is nearly complete. It explains the input and the detection scope. However, it omits the return format or expected output, which would help the agent process the result. For a simple check tool, this is a minor gap.
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 already describes the 'text' parameter with 100% coverage. The description adds value by specifying the kinds of injection attempts detected (instruction override, role hijacking, etc.), which informs the agent what kind of input is expected and what the check will look for. This goes beyond the schema's basic description.
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 'Check' and the specific resource 'user or agent input for prompt injection attempts'. It lists distinct detection categories (instruction override, role hijacking, etc.), which distinguishes it from sibling tools like scan_file (files) and scan_output (outputs). This is a specific and well-defined purpose.
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 the tool is for checking user or agent input, but it does not explicitly state when to use it versus alternatives like scan_file or scan_code. No when-not-to-use guidance or prerequisites are mentioned. The context is clear but not prescriptive, making it adequate but not excellent.
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 carries full responsibility for behavioral disclosure. The verb 'Get' strongly implies a read-only operation, and the content (health/configuration status) suggests no side effects. However, it does not explicitly state read-only behavior or any potential requirements (e.g., permissions, service availability), which would be valuable for a health/status command.
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 a single, focused sentence that directly states what is returned and lists the main categories. There is no redundant or filler text, making it highly concise and well-structured.
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 parameterless status tool with no output schema, the description is mostly sufficient. It names the key result areas (profile, scanners, audit statistics), but does not explicitly describe the response shape or any potential fields. Since it is a simple status read, this is a minor gap rather than a major omission.
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 tool has zero parameters, so the schema fully covers the input side. The description adds no parameter semantics, but none are needed. Per the rubric, the baseline for zero parameters is 4, which is appropriate here.
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 is specific and clear: it uses the verb 'Get' on the resource 'GuardianShield health and configuration status' and lists the key components (active profile, enabled scanners, audit statistics). This distinguishes it from siblings like get_profile (which likely returns only the profile) and audit_log (which likely returns log entries).
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 such as get_profile or audit_log. It does not mention any exclusions or alternative selection criteria, leaving the agent without direction for choosing among overlapping tools.
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 carries the burden for behavioral traits. It mentions returns match details but does not disclose side effects, error handling, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste, front-loaded with the action and result.
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 testing tool with three parameters (two required) and no output schema, the description covers purpose and output type but could mention handling of invalid regex or language context.
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 coverage is 100%, and the description adds no extra meaning beyond parameter names and the schema's own 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 tests a regex pattern against sample code and returns match details, distinguishing it from sibling tools which focus on scanning and security checks.
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 use for developing and debugging vulnerability patterns but does not explicitly compare to alternatives or state 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states that the finding will no longer be flagged in future scans, which is a key behavioral trait. However, it does not disclose whether the operation is reversible, requires authentication, what happens if the fingerprint does not exist, or other side effects. The disclosure is minimal but accurate.
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 wasted words. The description is front-loaded with the action and resource, followed by the consequence. Every sentence adds value.
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 tool with one parameter, no output schema, and no annotations, the description covers the essential: what it does, how (by fingerprint), and the effect. It does not mention error handling or prerequisites, but the tool is straightforward and the description is sufficient for an agent to understand its basic operation.
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% with a description for the 'fingerprint' parameter. The tool description repeats 'by its fingerprint' but adds no new meaning beyond the schema. Baseline 3 is appropriate because the schema already documents the parameter.
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 'remove' and the resource 'false positive record', and it distinguishes from siblings like mark_false_positive (adds) and list_false_positives (lists). The effect on future scans is also specified, making the purpose unambiguous.
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 when you want to undo a false positive marking, but it does not explicitly contrast with mark_false_positive or list_false_positives. No guidance on when not to use this tool or prerequisites (e.g., fingerprint must exist). Usage is inferred but not explicitly guided.
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 must disclose all behavioral traits. It correctly indicates that this tool scans code and creates a file (side effect). However, it does not specify whether the baseline file is overwritten, what the tool returns, the exact file format (JSON is mentioned but no structure), or any required permissions.
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 totaling ~30 words, with the core action front-loaded: 'Scan code and save the findings as a baseline JSON file.' Every part is necessary and functional with no filler.
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?
For a tool that both scans and persists state, the description explains the baseline workflow but omits the return value (e.g., scan results, confirmation, or baseline path). It also does not clarify default behavior if output_path is omitted, leaving the agent to rely on the schema's default value string. Given the complexity and lack of output schema, these gaps reduce completeness to adequate but not thorough.
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 coverage is 100%, so the schema already documents all parameters. The description adds marginal value beyond the schema by implying that output_path is the baseline save location. This meets the baseline of 3 but does not enrich parameter understanding beyond 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 it scans code and saves findings as a baseline JSON file, with a specific purpose: enabling differential reporting via scan_with_baseline. This distinguishes it from siblings like scan_code (which scans without saving) and scan_with_baseline (which consumes the baseline).
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 explicitly links save_baseline to a subsequent use of scan_with_baseline, telling the agent when to use this tool. It provides context about the differential workflow, though it does not explicitly state when not to use it or mention alternative scan-only tools.
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 carries the full burden. It discloses that only added lines are scanned and that findings have correct line numbers and file paths, which suggests a focused behavior on additions and accurate location mapping. However, it does not mention side effects, authorization needs, rate limits, or what happens to unchanged lines, so while useful, it could be more transparent.
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 two sentences long, conveying purpose, input type, and key behavior without any filler. It is efficient and front-loaded with the actionable verb and main subject.
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 tool has only one parameter, no output schema, and no annotations, so the description provides sufficient completeness for its simplicity. It explains what is scanned and the quality of results. However, given the sensitive nature of vulnerability scanning, noting typical output format or limitations would improve completeness slightly.
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 input schema has 100% coverage with a single parameter 'diff' described as 'Unified diff text (e.g. from git diff).' The description adds that the diff should be from git etc., and mentions scanning only added lines, but does not add formatting details or constraints beyond the schema. Since schema coverage is high, 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 tool scans a unified diff for vulnerabilities, which is a specific verb-resource combination. It distinguishes itself from sibling tools like scan_file or scan_code by focusing on diff input, and it clarifies that only added lines are scanned, which is unique among the siblings.
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 implies when to use this tool: when you have a unified diff (e.g., from git diff) and want to scan for vulnerabilities. It provides context on what is scanned (only added lines) and correct output assignments, but does not explicitly mention when not to use it or suggest alternatives among siblings, so the guidance is good but not comprehensive.
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 are provided, so the description bears full burden. It discloses that PII is automatically redacted in findings, which is a key behavioral trait. However, it does not clarify whether the tool modifies the original text, whether redaction is reversible, what the return format looks like, or whether there are any rate limits 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose, then add the key behavioral detail about redaction. Every sentence is necessary and there is no filler. Perfectly sized for the complexity of the tool.
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 only one simple string parameter and no output schema, the description covers the core intent and a notable behavior (redaction). It could optionally mention that results are returned as findings (referencing sibling get_findings), but is otherwise complete for a scanning tool with straightforward usage.
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 100% (one parameter 'text' with description 'The AI output text to scan.'). The tool description adds value by explaining what the scan checks for (PII leaks, content violations) and that redaction occurs, which goes beyond the schema's minimal description. Together, they give complete semantic clarity for the single parameter.
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 specifies a clear verb ('Check') and resource ('AI-generated output'), and enumerates the exact categories scanned (PII like email, SSN, credit card, phone, IP; policy violations like violence, self-harm, illegal activity). It distinguishes itself from siblings like scan_file, scan_code, scan_input, and check_secrets by focusing on AI output and listing specific PII types and policy categories.
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 scanning AI output, but does not explicitly state when to prefer this over alternatives like scan_input (which might scan user input) or check_secrets (which might scan for secrets). Provides no when-not-to-use guidance or preconditions.
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 are provided, so the description carries the full burden. It clearly states that the tool returns a verdict (pass/fail/warn) and exit codes, which is useful for behavioral understanding. However, it does not disclose whether the tool is destructive, reads data, requires authentication, or has rate limits. For a tool that scans code, these are important but less critical than for mutation tools, so the score is slightly below a 5.
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 three concise sentences, each adding distinct value: first sentence defines the core action, second states the output verdict, third specifies exit codes. There is no redundant or wasted text.
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 params, 1 required) and no output schema, the description provides the key missing piece by explaining the return verdict and exit codes. However, it does not describe what happens with the optional parameters (e.g., 'fail_on' and 'warn_on' behavior is implied but not explained), which could enhance completeness. Still, the description resolves the main gap for a tool that returns a verdict rather than raw findings.
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 input schema has 100% description coverage, so the schema already documents all parameters. The description adds no additional parameter-level meaning beyond what the schema provides. According to the rubric, when schema_description_coverage is high (>80%), the baseline is 3, and the description does not exceed that baseline.
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 uses a specific verb phrase 'Scan code and evaluate findings against configurable severity thresholds' and explicitly distinguishes the tool's purpose from its siblings by naming the output verdict ('pass/fail/warn') and CI pipeline use case. This clearly differentiates it from scanning tools like 'scan_code' or 'scan_file' which presumably only scan without evaluating against thresholds, and from 'check_secrets' which has a narrower focus.
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 strong usage context by mentioning suitability for CI pipelines and specifying exit codes (0=pass, 1=fail). However, it does not explicitly state when to use this tool versus its many siblings (e.g., when to choose 'check_quality_gate' over 'scan_code' or 'scan_file'), nor does it mention exclusions or prerequisites. The CI pipeline mention is a clear use case but does not fully guide agent decision-making among alternatives.
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:

[![GuardianShield MCP server](https://glama.ai/mcp/servers/sparkvibe-io/GuardianShield/badges/card.svg)](https://glama.ai/mcp/servers/sparkvibe-io/GuardianShield)

Score Badge

Copy to your README.md:

[![GuardianShield MCP server](https://glama.ai/mcp/servers/sparkvibe-io/GuardianShield/badges/score.svg)](https://glama.ai/mcp/servers/sparkvibe-io/GuardianShield)

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/sparkvibe-io/GuardianShield'

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