Skip to main content
Glama
nikshitharapolu

CreditDelta MCP Guardian

CreditDelta MCP Guardian

The CreditDelta MCP Guardian is a local, scientifically proven financial analysis server and security control layer for AI tool requests. The CreditDelta publishes its publicly available SEC financial analyses via MCP; the Guardian will determine whether an action request will be allowed, denied, or will need a special human permission.

All core financial and security functions use locally installed software that is free and open-source. Gemini reporting is optional and will default to deterministic templates if there's no API.

Live Demo

Try the deployed application: CreditDelta MCP Guardian

Related MCP server: SEC EDGAR Data MCP

Why this exists

The MCP approach enables AI-based applications to utilize external utilities; however, an able-bodied agent can get a malicious command, have too many permissions, expose private information, and do irreversible damage. In this project, least privilege, default deny, human approval, redaction auditing, and reproducible security assessment is done on tool invocations.

flowchart LR
    U[User] --> A[AI or Inspector]
    A --> G[MCP Guardian]
    G -->|Allow| C[CreditDelta and local tools]
    G -->|Approval| H[Human decision]
    G -->|Deny| X[Blocked]
    C --> L[Redacted audit log]
    H --> L
    X --> L

Capabilities

  • search_company: find a company by name or ticker and return its SEC CIK.

  • list_metric_periods: retrieve recent reported values for one metric.

  • compare_financials: compare the two most recent periods and return the absolute change, percentage change, direction, and SEC accession evidence.

  • creditdelta://metrics: discover the metrics supported by the server.

  • evaluate_tool_call: classify a proposed MCP action as ALLOW, DENY, or REQUIRE_APPROVAL before it executes.

  • guarded_action: enforce the policy and either execute, block, or queue the action for approval.

  • resolve_approval: explicitly approve or reject one queued action.

  • list_pending_actions: inspect actions awaiting a decision.

  • list_audit_events: inspect redacted Guardian decisions and outcomes.

  • run_security_benchmark: measure attack blocking, false positives, controlled action accuracy, and policy latency.

  • generate_report: creates an editable financial narrative grounded in deterministic SEC facts, with a template fallback when Gemini is unavailable.

  • The web application lets users review and download generated reports.

  • MCP prompts provide reusable company-analysis and security-review workflows.

Supported starter metrics are revenue, cash, the current portion of long-term debt (current_debt), net income, and operating cash flow. SEC XBRL tags vary across companies, so missing or non-comparable values are returned as clear errors instead of being invented.

CreditDelta is a learning and research project. It does not provide credit ratings, investment advice, or predictions.

Project structure

creditdelta-mcp/
├── .github/workflows/tests.yml
├── .streamlit/config.toml
├── requirements.txt
├── compose.yaml
├── Dockerfile
├── pyproject.toml
├── README.md
├── SECURITY.md
├── src/creditdelta_mcp/
│   ├── benchmark.py     # repeatable security evaluation
│   ├── dashboard.py     # user-facing Streamlit application
│   ├── enforcement.py   # approvals, execution, and audit log
│   ├── finance.py       # deterministic financial comparisons
│   ├── guardian.py      # allow/deny/approval policy engine
│   ├── sec_client.py    # allowlisted SEC JSON access
│   └── server.py        # MCP tools, resources, and prompts
│   ├── report_generator.py  # grounded Gemini reports and template fallback
└── tests/               # unit and integration tests

The financial calculations are deliberately separated from MCP. This makes them easy to test and later lets MCP Guardian inspect tool requests before the tools execute.

Run locally (macOS)

Python 3.10 or newer is required. From the project directory:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev,dashboard]'

The SEC asks automated clients to identify themselves. Use your own name and email address:

export SEC_USER_AGENT="Your Name your.email@example.com"

Gemini report generation is optional. Create a key through Google AI Studio, then set:

export GEMINI_API_KEY="gemini-api-key"
export GEMINI_MODEL="gemini-3.6-flash"

Run the automated tests:

```bash
python -m pytest

Open the server with MCP Inspector:

mcp dev src/creditdelta_mcp/server.py
creditdelta-benchmark
creditdelta-mcp

You can then try:

  1. search_company with {"query": "AAPL"}.

  2. Copy the returned CIK.

  3. Call compare_financials with {"cik": "0000320193", "metric": "revenue", "form": "10-Q"}.

Security decisions already present

  • Network access is fixed to official SEC endpoints.

  • CIK, metric, form, count, and search limits are validated.

  • Calculations are deterministic Python code; an LLM does not calculate values.

  • Results include filing accession identifiers as evidence.

  • Missing data fails closed with an error rather than a fabricated value.

See SECURITY.md for the threat model, trust boundaries, controls, and limitations.

MCP Guardian policy engine

The deterministic policy engine produces one of three decisions:

ALLOW             safe read-only operation
REQUIRE_APPROVAL  sensitive or external operation
DENY              policy violation

Current rules automatically allow public CreditDelta reads, deny unknown tools and paths outside the approved reports directory, require approval for writes, deletions, and ordinary email, and block email containing detected secrets or financial identifiers. An LLM is not allowed to override these decisions.

Guarded execution

Local MCP file operations are restricted to .creditdelta_data/reports. The public web application creates a separate temporary directory under .creditdelta_data/sessions/<session-id>/ for each browser session. Writes and deletions require approval. Deletion moves a file into a recoverable local trash directory instead of permanently erasing it. Email is simulated by writing to a local outbox, it never contacts a real email service. Every policy decision and execution outcome is stored in a local SQLite audit database, and sensitive arguments are redacted from the audit view.

Benchmark and dashboard

Run the security benchmark from the command line:

creditdelta-benchmark

Launch the complete user-facing web application:

python -m streamlit run src/creditdelta_mcp/dashboard.py

The application provides four pages:

  • Company Analysis: searches public companies, compares SEC financial periods, generates grounded reports, and supports report downloads.

  • Guardian Playground: demonstrates protected file operations, simulated email, secret detection, and default-deny behavior.

  • Approvals & Audit: supports self-confirmation of sensitive actions and displays redacted audit events.

  • Security Benchmark: evaluates safe, controlled, and adversarial policy cases.

MCP Inspector remains the developer-facing interface for testing tools, resources, and prompts.

The benchmark contains safe, controlled, and adversarial cases. It reports the attack block rate, false-positive rate for safe actions, approval accuracy, and average policy latency. These results describe this fixed test suite; they are not a claim that every possible MCP attack is blocked.

One local reference run on macOS produced 14/14 expected decisions, a 100% attack-block rate on eight included adversarial cases, a 0% false-positive rate on three included safe cases, and 0.0145 ms average policy latency. Latency is machine-dependent; rerun the benchmark on your system before reporting it.

Docker

The dashboard can run in Docker with persistent local audit data:

cp .env.example .env
docker compose up --build

Open http://localhost:8501. Docker is optional; the regular Python setup is the simplest way to run MCP Inspector.

Free public deployment

The simplest portfolio deployment is Streamlit Community Cloud:

  1. Push this project to a GitHub repository.

  2. In Streamlit Community Cloud, create an app from that repository.

  3. Set the app entry point to src/creditdelta_mcp/dashboard.py.

  4. In the app's Secrets settings, add:

    SEC_USER_AGENT = "youremail@gmail.com"
    GEMINI_API_KEY = "gemini-api-key"
    GEMINI_MODEL = "gemini-3.6-flash"
  5. Deploy and use the generated public URL in your resume or GitHub README.

The included requirements.txt and .streamlit/config.toml make the hosted build reproducible and keep typography consistent across Safari, Chrome, and Firefox. Reports, approvals, and audit records are isolated by browser session but stored on the hosted application's temporary filesystem. They may disappear when the application restarts or redeploys. Users should download reports they want to keep.

Each browser session receives an isolated report, approval, and audit directory. The report generator sends only verified public SEC facts to Gemini; Python appends the authoritative values and filing accessions. If the key, quota, or configured model is unavailable, the application automatically produces a deterministic template report instead.

Continuous integration

The included GitHub Actions workflow tests Python 3.11 and 3.13 and runs the security benchmark on every push and pull request.

Project status

This is a prototype. Browser sessions are isolated but not authenticated user accounts. Production extensions would include OAuth 2.1 for remote MCP transport, authentication, role-based authorization, durable database and object storage, distributed rate limiting, stronger secret detection, signed tool manifests, and a larger independently labeled adversarial evaluation set.

Available Tools

9 tools
compare_financialsC

Compare the two most recent SEC values for one financial metric.

ParametersJSON Schema
NameRequiredDescriptionDefault
cikYes
formNo10-Q
metricYes

TDQS

C2.7/5.0
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 behavioral disclosure burden. It states the core comparison but does not disclose return format, read-only status, how missing values are handled, or how the 'two most recent' values are selected across forms.

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 front-loaded sentence with no filler; the core action and target are immediately visible. It is under-specified semantically, but structurally it is concise and well-organized.

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?

With no annotations, no output schema, and three undocumented parameters, a one-sentence description is insufficient. An agent cannot determine how cik and metric should be formatted, what forms are involved, what the comparison result looks like, or how this relates to list_metric_periods.

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?

Schema description coverage is 0%, so the description must compensate. It loosely maps 'metric' to the financial metric and 'SEC' to the company context, but it does not explain the cik parameter, the role of form, or accepted values/formats for any 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 uses a specific verb ('Compare') and identifies the resource ('two most recent SEC values for one financial metric'), making the core operation clear. It does not explicitly differentiate from siblings like list_metric_periods, but the compare action is distinct enough for basic selection.

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?

There is no guidance on when to use this tool versus alternatives such as list_metric_periods, which likely provides the underlying periods/values. The phrase 'two most recent' implies recency context, but the description does not explain prerequisites, exclusions, or when another tool should be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

evaluate_tool_callC

Ask MCP Guardian whether a proposed tool call is safe to execute.

ParametersJSON Schema
NameRequiredDescriptionDefault
argumentsYes
tool_nameYes

TDQS

C2.7/5.0
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 communicates that the tool is advisory rather than executing ('Ask ... whether'), but it does not disclose the return shape, side effects, latency, permissions, or whether an unsafe result triggers an approval workflow. This is minimal transparency beyond the schema.

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, front-loaded sentence with no filler; every word contributes to stating the tool's purpose. However, the brevity leaves out behavioral and usage details, making it concise but slightly under-specified.

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?

For a security-evaluation tool with no annotations, no output schema, and a free-form arguments object, the description is too thin. It does not state what the response contains, when to use this tool relative to guarded_action or resolve_approval, or how the arguments are validated. An agent can make a first guess but lacks enough detail to call confidently.

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?

Schema description coverage is 0%, and the description does not explain tool_name or the arguments object. 'Proposed tool call' loosely implies both parameters, but it never clarifies that tool_name must reference a registered tool or that arguments should mirror the call being evaluated. The free-form arguments object remains largely undefined.

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 uses a clear verb ('Ask'), names the resource ('MCP Guardian'), and defines the object ('proposed tool call'), making the core function obvious. It doesn't explicitly distinguish itself from siblings like guarded_action or resolve_approval, but the 'safe to execute' framing makes its advisory nature reasonably clear.

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 call this tool versus alternatives. The description implies a pre-execution safety check, but it does not state that guarded_action should be used to actually run the call, nor what to do if the result is unsafe. Agents must infer usage context from the name and sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

guarded_actionC

Evaluate and safely execute, block, or queue a protected local action.

ParametersJSON Schema
NameRequiredDescriptionDefault
argumentsYes
tool_nameYes

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of explaining behavior. It does disclose three possible outcomes (execute, block, queue), but it omits what evaluation criteria are used, what side effects occur, whether approval is required, and what happens to a blocked or queued action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single economical sentence with no obvious filler, but it is under-specified to the point of missing essential operational context. It reads as terse rather than deliberately concise.

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?

For a guarded execution tool with two required parameters, nested arguments, no output schema, and no annotations, the description is far too incomplete. It does not cover return values, approval flow, error behavior, or how this tool relates to siblings such as list_pending_actions and resolve_approval.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not mention tool_name or arguments. The agent receives no guidance on what tool_name should contain, what shape arguments should take, or how the payload relates to the protected action being executed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb phrase ('evaluate and safely execute, block, or queue') and names a resource ('protected local action'), so it is not a tautology. However, 'protected local action' is vague and the description does not differentiate it from sibling tools such as evaluate_tool_call or resolve_approval.

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 when-to-use or when-not-to-use guidance is provided. The only implicit signal is the phrase 'protected local action,' but the description never clarifies when this guarded wrapper should be preferred over directly invoking a tool or over sibling tools like resolve_approval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_audit_eventsB

Return recent redacted Guardian decisions and execution outcomes.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that results are 'redacted' and limited to 'recent' events, which adds meaningful behavioral context. However, it does not mention ordering, pagination, access requirements, or whether the operation is strictly read-only beyond the name 'list'.

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, front-loaded sentence with no filler. It efficiently conveys the core purpose and key behavioral trait ('redacted') in minimal 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 is simple, with one optional parameter and an output schema, so the description does not need to explain return values. However, the ambiguous 'Guardian' terminology and absence of usage guidance leave the definition minimally viable rather than fully complete.

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?

Schema description coverage is 0%, and the description does not mention the 'limit' parameter at all. The parameter name and default value make it self-evident, but the description adds no meaning beyond the schema, so it fails to compensate for the lack of schema documentation.

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 uses a clear verb ('Return') and names a specific resource ('recent redacted Guardian decisions and execution outcomes'). It is specific enough to distinguish from siblings like list_pending_actions, though it does not explicitly contrast with any sibling.

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 implies the tool is for retrieving audit history but provides no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_pending_actions. An agent must infer the usage context from the tool name and brief purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_metric_periodsC

List recent SEC values for a supported financial metric.

Supported metrics: revenue, cash, current_debt, net_income, operating_cash_flow.

ParametersJSON Schema
NameRequiredDescriptionDefault
cikYes
formNo10-Q
countNo
metricYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It states that the tool lists values, implying a read-only operation, but fails to define 'recent,' explain the count/form defaults, or describe the output. No rate limits, auth requirements, or edge cases are mentioned.

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?

At just two sentences, the description is exceptionally lean and starts with the core action. The supported-metrics list is useful and placed toward the end, minimizing distraction. No unnecessary filler is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with four parameters, no output schema, and no annotations, the description is severely incomplete. It does not clarify that periods are being returned, what cik should be, which forms are valid, or what 'recent' means. An agent would struggle to know what to pass for three of the four parameters.

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?

Schema description coverage is 0%, so the description must compensate. It only enumerates valid values for the metric parameter; cik, form, and count are left completely unexplained. This is insufficient for an agent to construct valid arguments reliably.

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 uses 'List recent SEC values for a supported financial metric,' which is a specific verb-resource pairing. The explicit list of supported metrics helps disambiguate from broader financial tools, though it doesn't explicitly differentiate from siblings like compare_financials.

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 is given about when to use this tool versus alternatives such as compare_financials or search_company. The only usage hint is the supported metrics list, which implies eligibility but provides no exclusions or selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_pending_actionsA

List actions waiting for explicit user approval.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It clearly indicates a read-only listing of pending actions, but it does not disclose additional behavioral details such as sorting, ordering, or whether the list is scoped to the current user. This is adequate but not rich.

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, front-loaded sentence with no filler. Every word adds meaning, and it is immediately actionable.

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 no parameters and an output schema exists, the description is largely complete. It lacks explicit routing to sibling tools or caveats, but the simplicity of the tool makes this 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 tool has zero parameters, so parameter documentation is not needed. The description adds no parameter semantics, but the input schema is empty, so there is nothing missing.

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 states a specific verb ('List') and resource ('actions waiting for explicit user approval'), making the tool's purpose clear. It does not explicitly name sibling tools, but the phrase 'waiting for explicit user approval' distinguishes it from resolve_approval and guarded_action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when a user wants to see actions that require explicit approval. It does not explicitly exclude alternatives like resolve_approval or list_audit_events, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_approvalB

Approve or reject one pending guarded action.

ParametersJSON Schema
NameRequiredDescriptionDefault
approveYes
approval_idYes

TDQS

B3.3/5.0
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 states the operation type but does not disclose what happens after approval or rejection, whether the action executes, whether the resolution is reversible, or what permission or auditing side effects may occur.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, containing no filler or redundant information, and the core action is front-loaded in a single short sentence.

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?

The tool is simple, but with no annotations and no output schema, the description still leaves important context unresolved: what a 'guarded action' is, what happens after resolution, and what the return value or error behavior looks like.

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?

Schema description coverage is 0%, and the description does not compensate by explaining the parameters. 'approve' is partially self-explanatory from the verb, but approval_id receives no semantic context such as where it comes from or what format it follows.

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 ('approve or reject') with a clear resource ('one pending guarded action'), and it is immediately distinguishable from siblings like list_pending_actions, which handles listing rather than resolving.

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 is used to resolve a pending guarded action, which suggests pairing with list_pending_actions, but it does not explicitly state when to use this tool versus alternatives or mention any prerequisites such as obtaining an approval_id first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_security_benchmarkA

Measure Guardian correctness and decision latency on adversarial cases.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description clearly frames the tool as a measurement/evaluation action rather than a data-mutating one, which is a useful behavioral signal. With no annotations, though, it does not disclose possible runtime cost, side effects, or what running a benchmark may do to the system.

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 compact sentence that front-loads the action and object. There is no filler, redundancy, or unnecessary detail.

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 zero-parameter tool, the description is mostly sufficient to decide whether to invoke it, and it clearly states what is being measured. However, there is no output schema and the description does not disclose what the benchmark returns, such as a report, pass/fail results, or metrics, which an agent would need to interpret the outcome.

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 there is no parameter-semantics burden on the description. The schema already covers 100% of the parameter surface, and the description appropriately treats this as a parameterless invocation.

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 names a specific verb ('Measure'), a specific resource ('Guardian correctness and decision latency'), and a context ('adversarial cases'), which clearly distinguishes this as a benchmark/evaluation tool. Even without a title, an agent can infer its role relative to the action/list sibling tools.

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 for evaluating Guardian on adversarial cases, and the tool name reinforces the benchmarking intent. However, it does not explicitly state when to prefer this over alternatives like evaluate_tool_call or guarded_action, and it offers no prerequisites or environment expectations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_companyA

Find a public company and its SEC CIK using a name or ticker.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
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 communicates a basic lookup but does not say whether matching is exact or partial, whether multiple results can be returned, or what the limit parameter affects. This could lead an agent to expect a single unique result.

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, front-loaded sentence with no filler. Every word contributes to the tool's purpose and input modes, making it easy for an agent to scan quickly.

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 output schema presumably covers return values, and the description covers the primary query semantics. Still, with no annotations, the definition lacks guidance on search behavior such as partial matches, multiple candidates, and the meaning of the limit parameter. It is adequate but leaves meaningful gaps.

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 0%, so the description must compensate. It does add important meaning by explaining that the query parameter accepts a name or ticker. However, it says nothing about the limit parameter, though the limit name and default make its purpose partially inferable.

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 states a specific verb ('Find'), a concrete resource ('public company and its SEC CIK'), and the accepted inputs ('name or ticker'). This clearly differentiates it from the sibling tools, which are about actions, approvals, metrics, and comparisons.

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 clear context: use this tool when you need to resolve a company name or ticker to a public company and its CIK. It does not explicitly mention alternatives or exclusions, but no sibling tool overlaps directly with this lookup purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv1.4.0
    • First observedcompare_financials
    • First observedevaluate_tool_call
    • First observedguarded_action
    • First observedlist_audit_events
    • First observedlist_metric_periods
    • First observedlist_pending_actions
    • First observedresolve_approval
    • First observedrun_security_benchmark
    • First observedsearch_company

TDQS

B3.3/5.0

Scored across 9 tools

Disambiguation5/5

The tools fall into two distinct clusters (guardian/security and financial data) with clear boundaries. Within the guardian cluster, guarded_action and evaluate_tool_call differ by scope (local actions vs. tool calls), and list/resolve/benchmark tools are unambiguous. Financial tools are clearly distinct by resource (company, metrics, comparison). No two tools could be easily confused.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (guarded_action, resolve_approval, list_pending_actions, etc.). Each starts with a clear verb and uses a descriptive noun, making the pattern predictable across both clusters.

Tool Count5/5

With 9 tools, the server is well-scoped for its combined purpose of security guard and financial data lookup. Each tool serves a necessary function without redundancy, and the count is comfortably within the ideal 3–15 range.

Completeness4/5

The guardian workflow is fully covered: evaluation, execution, approval, pending list, audit log, and benchmarking. Financial data supports search, metric listing, and comparison, but lacks a tool to retrieve raw multi-period values or detailed financial statements, which agents may need to infer from comparisons.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers