Skip to main content
Glama
DeployAngel

DeployAngel

by DeployAngel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

DeployAngel for Python

The DeployAngel agent for Django, FastAPI, Starlette, and Flask, with Celery and RQ jobs. It watches what your app does in production and reports one small aggregated payload per process per minute. DeployAngel uses that to verify every deployment, and to tell you (or your coding agent) when a release is cleared and you can stop watching it.

Install

Requires Python 3.10 or later. The package has no dependencies of its own.

pip install deployangel

Set this in production, for every process (web servers and job workers alike):

DEPLOYANGEL_TOKEN=da_live_...           # an ingestion token with the telemetry scope

On Heroku, the DeployAngel add-on sets it for you.

Django

Supports Django 4.2 or later.

# settings.py
INSTALLED_APPS = [
    # ...
    "deployangel.django",
]

That's all. The app puts DeployAngel's middleware at the top of MIDDLEWARE (list it yourself to place it), records requests under WSGI and ASGI, and instruments Celery when it's installed. Reporting is on when DEBUG is off.

FastAPI and Starlette

Supports FastAPI 0.100 and Starlette 0.27 or later.

import deployangel.fastapi

app = FastAPI()
deployangel.fastapi.init(app)      # deployangel.starlette.init(app) for Starlette

Call it where the app is created, before it serves requests.

Flask

Supports Flask 2.3 or later.

import deployangel.flask

app = Flask(__name__)
deployangel.flask.init_app(app)

Celery

Supports Celery 5.3 or later. In Django it's automatic. Elsewhere, call init where the Celery app is created, so worker processes start the agent:

import deployangel.celery

app = Celery("shop")
deployangel.celery.init(app)

RQ

Supports RQ 1.16 or later. Run workers with DeployAngel's worker class:

rq worker -w deployangel.rq.Worker               # or deployangel.rq.SimpleWorker
python manage.py rqworker --worker-class deployangel.rq.Worker   # django-rq

RQ runs each job in a forked process that exits as soon as the job ends, so the worker records each job after it finishes, from what RQ saved in Redis. That includes a failed job's traceback, but not the exception of an attempt RQ retries.

Which release is running

The agent must know which release it's running. It finds it in this order:

  1. DEPLOYANGEL_REVISION (the commit SHA) and DEPLOYANGEL_RELEASE_VERSION, if you set them

  2. Heroku dyno metadata. Enable it with heroku labs:enable runtime-dyno-metadata and heroku labs:enable runtime-dyno-build-metadata; both take effect on the next deploy

  3. Kamal: KAMAL_VERSION

  4. Render: RENDER_GIT_COMMIT

  5. Fly.io: the deploy's image tag, from FLY_IMAGE_REF. Fly.io sets no commit, so pass one in for commit-level change tracking (ENV DEPLOYANGEL_REVISION=$GIT_SHA in the Dockerfile, with --build-arg GIT_SHA=$(git rev-parse HEAD))

  6. Railway: RAILWAY_GIT_COMMIT_SHA, or RAILWAY_DEPLOYMENT_ID

  7. Coolify: SOURCE_COMMIT. Dokku: GIT_REV

  8. a REVISION file in the app's root

  9. a git checkout: the commit HEAD names, read from .git in the app's root or up to 3 directories above it, without running git. This covers servers deployed by git pull, Fabric, or Ansible

  10. ECS, including Fargate: the container's image, from the metadata endpoint ECS provides (one local request at boot)

  11. a code fingerprint: code: and the first 12 characters of the hash of the file digests the agent already sends (below), with no commit. The same code gives the same fingerprint, so a redeploy of unchanged code isn't a new release. It's computed in the background when the reporter starts, not at boot, and needs file digests on. Without a commit DeployAngel still shows which files changed in a release, but not its commits and pull requests, so the agent logs a warning: set DEPLOYANGEL_REVISION when you can

For other Docker deploys, bake the commit into the image: deployangel install docker adds ARG GIT_SHA and ENV DEPLOYANGEL_REVISION=$GIT_SHA to the end of your Dockerfile, where it doesn't invalidate cached layers, and you build with --build-arg GIT_SHA=$(git rev-parse HEAD). On DigitalOcean App Platform, set DEPLOYANGEL_REVISION: ${_self.COMMIT_HASH} in the app spec.

Related MCP server: jenkins-mcp

What it sends

  • HTTP request counts, 4xx/5xx counts by status code, unhandled exceptions, and a latency histogram, both per app and per route.

  • Routes are recorded as the pattern the framework matched (GET /users/<int:pk>/, GET /items/{item_id}), never the raw path. At most 100 routes are sent per payload; the rest are folded into __other__.

  • Background jobs: attempts, failed attempts, discarded jobs, duration, and queue latency, per task. For queue latency, Celery task messages carry one extra header, deployangel_published_at, the time they were sent.

  • Tasks still running at the end of each minute, and how long the oldest of each has been running, so a task that hangs is noticed.

  • Release identity, runtime versions, and a per-process instance ID.

  • Exceptions: a stable fingerprint, the exception class, the first line of the message, and application frames only (file paths and function names). In the message, numbers, IDs, emails, UUIDs, long hex strings, quoted values, and the request's host are replaced with placeholders. Other words are kept: Payment failed for Jane Doe is sent as it is. If your app's messages might hold personal or health data, turn messages off.

  • Once per process: the route table (with each view's module and file), task names and files, recurring schedules declared for Celery Beat (in settings or in django-celery-beat's tables), critical flows, and file digests (relative paths and hashes, never file contents) so DeployAngel can tell which routes changed in a release. Disable digests with DEPLOYANGEL_FILE_DIGESTS=false.

It does not send request bodies, parameters, headers, cookies, SQL, logs, or user data.

Data and pricing

  • Everything goes to DeployAngel's hosted service, which runs on DigitalOcean in the United States. There's no self-hosted version, and no choice of region.

  • Telemetry is kept for 21 days, and release history for 7, 30, or 90 days depending on the plan. The privacy policy has the details and the services DeployAngel uses.

  • DeployAngel is free during the beta, with notice before paid plans start. See pricing.

Safety

  • Nothing runs on the network during a request or job. Recording only updates in-memory counters.

  • Payloads are sent from a background thread, once a minute, with short timeouts.

  • When DeployAngel is unreachable, the buffer is bounded (10 payloads, kept as gzipped JSON) and the oldest are dropped. Your app is never blocked or failed.

  • Safe across forks (Gunicorn, Celery's prefork pool, uWSGI), and the minute in progress is flushed at shutdown. Under uWSGI, enable threads (enable-threads = true).

python bench/overhead.py measures this. On an Apple M-series laptop with Python 3.14, recording a request adds about 1.7 µs, and with every route, job, checkpoint, and exception list at its cap the agent holds about 0.5 MB, including 10 unsent minutes.

Configuration

Environment variables are enough for most apps. In Django, settings go in a DEPLOYANGEL dict; elsewhere, call deployangel.configure before init:

# settings.py
DEPLOYANGEL = {
    "environments": ["production", "staging"],   # default: production only
}

# or anywhere else
deployangel.configure(environments=["production", "staging"])

The agent reports in the environments listed. Python frameworks don't name an environment, so it's DEPLOYANGEL_ENVIRONMENT if set, otherwise development when the framework's debug mode is on and production when it's off. DEPLOYANGEL_ENABLED=true|false forces reporting on or off anywhere. DEPLOYANGEL_URL overrides the API endpoint (default https://api.deployangel.com).

File paths are relative to the app's root, the working directory by default (on Heroku and in most containers, the repository's root). Set DEPLOYANGEL_ROOT if your processes start somewhere else.

Critical flows (for example sign-up or password reset) are always listed in clearance reports:

DEPLOYANGEL = {
    "critical_flows": {"password_reset": ["POST /password-reset/", "job:accounts.tasks.send_reset_email"]},
}

Health checks aren't recorded: load balancers and uptime monitors call them all the time and they always answer fast, so they would make your app look busier and healthier than its real pages. The agent recognizes django-health-check, django-alive, and django-watchman wherever they're mounted, and any route at a conventional path (/up, /health, /healthz, /healthcheck, /health_check, /livez, /readyz, /statusz, /ping, /ht, /alive). If yours is somewhere else, list it the way the dashboard shows it. HEAD requests to it are left out too:

DEPLOYANGEL = {"ignored_routes": ["GET /status/"]}

Exception messages

To send exceptions without any message, only their class, fingerprint, and application frames:

DEPLOYANGEL = {"exception_messages": False}   # or DEPLOYANGEL_EXCEPTION_MESSAGES=false

Grouping, new-exception detection, and verdicts work the same, since the fingerprint never uses the message. You lose the message text in the dashboard, notifications, and AI investigation.

Handled exceptions

Exceptions your code catches aren't seen. To report one for context (handled exceptions never fail a release):

try:
    sync_inventory()
except UpstreamError as error:
    deployangel.notify(error)

Recurring jobs

DeployAngel expects declared recurring tasks on schedule. It reads Celery Beat's beat_schedule (crontabs, and intervals, which repeat from when Beat starts) in the zone Celery uses, and, when django_celery_beat is installed, its enabled periodic tasks. Solar schedules aren't read, and neither are RQ's schedulers, whose jobs live only in Redis. DeployAngel also learns recurring jobs from their history.

Cron, Heroku Scheduler, and django-crontab

Work that something outside the app starts on a schedule, such as cron, Heroku Scheduler, or a Kubernetes CronJob, is invisible to Celery Beat. Declare it by the name it runs under, with a cron line or words like "every day at 4am", in the server's time zone unless you add one ("0 3 * * * America/New_York"):

DEPLOYANGEL = {
    "recurring_jobs": {
        "shop.tasks.send_receipts": "0 3 * * *",            # a Celery or RQ task
        "manage.py send_invoices": "every day at 4am",      # python manage.py send_invoices
        "nightly import": "30 2 * * *",                     # deployangel.task("nightly import")
    },
}

  • A task is recorded wherever it runs.

  • A Django management command named "manage.py <command>" is recorded with no code change.

  • Any other code is recorded when you wrap it. Exceptions are recorded and re-raised:

    with deployangel.task("nightly import"):
    run_import()

@deployangel.task("nightly import")
def run_import(): ...

django-crontab's CRONJOBS setting is read automatically when django_crontab is installed: each job is expected on its schedule in the server's zone, and its runs are recorded with no change to the job (a job that calls call_command is recorded as manage.py <command>).

Checkpoints

Errors and latency don't catch work that silently stops happening. Count the business events that matter with one line:

deployangel.checkpoint("order.created")
deployangel.checkpoint("webhook.stripe.processed", count=len(events))

DeployAngel learns each checkpoint's normal rate relative to your traffic and fails a release after which it drops sharply or stops, even when every request and job still succeeds. Only drops are flagged, and a checkpoint without enough traffic never blocks a release from being cleared. Checkpoints can also be part of a critical flow (checkpoint:order.created).

The agent also records whether each checkpoint happened while handling an HTTP request or while running a job (a Celery task or RQ job, including one run eagerly inside a request), so DeployAngel compares it against the right traffic: requests for checkpoints recorded in requests, job runs for ones recorded in jobs.

It's safe to call anywhere: it never raises, never touches the network, and is ignored outside reporting environments. Names use letters, numbers, and . _ : - (up to 100 characters); keep them to a fixed set rather than including IDs, since only 100 distinct names are counted per minute.

Registering deploys

DeployAngel notices a new release when the agent first reports it, and verifies it from there, with nothing to set up. On Heroku, the add-on also registers every release for you.

To register deploys from CI, which also catches a release that never boots, use an API token created for CI deploys in the dashboard. On GitHub Actions, add DeployAngel/verify-release after your deploy step: it registers the deploy, waits for the verdict, and fails the step if the release fails.

- uses: DeployAngel/verify-release@v1
  with:
    api-token: ${{ secrets.DEPLOYANGEL_API_TOKEN }}

Anywhere else, post the commit:

curl -fsS https://api.deployangel.com/api/v1/deployments \
  -H "Authorization: Bearer $DEPLOYANGEL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"commit\": \"$GIT_SHA\"}"

Command line and coding agents

The package includes the deployangel command (also python -m deployangel) and an MCP server for coding agents. They talk only to DeployAngel's API: they never start the agent or load your app, so they run anywhere the package is installed, or with nothing installed through uvx deployangel. Give them a token in DEPLOYANGEL_API_TOKEN: a "CLI & coding agents" token reads verdicts, and a "CI deploys" token can also register deploys and report checks.

To let a coding agent set DeployAngel up, use "Set up with your coding agent" on the app's page in DeployAngel: it gives a one-time setup code, not tokens. deployangel setup --code=CODE redeems it and saves the app's token and a "CI deploys" token to .deployangel/credentials.json, readable only by you and kept out of git, without printing either. The command and MCP server then use the saved token whenever DEPLOYANGEL_API_TOKEN isn't set. deployangel token app (or api) prints a saved token for piping into a host's or CI's secrets, so it never appears on screen or in an agent's conversation:

fly secrets set DEPLOYANGEL_TOKEN=$(deployangel token app)
deployangel token api | gh secret set DEPLOYANGEL_API_TOKEN
deployangel verify --wait                   # current git HEAD, until a verdict
deployangel verify --wait --until=initial   # return at the 15-minute initial check
deployangel status                          # latest deployment
deployangel plan                            # what to exercise so a release clears sooner
deployangel exercise --url=https://example.com  # send the plan's read-only requests to production
deployangel release --commit=$SHA           # register a deploy (manual or CI)
deployangel check --name="smoke: signup" --status=pass --covers=registration
deployangel install kamal                   # a Kamal post-deploy hook that registers each deploy
deployangel install docker                  # bake the commit into the image as DEPLOYANGEL_REVISION
deployangel install agents                  # set up Claude Code, Cursor, and Codex in this project
deployangel doctor                          # check the setup

deployangel doctor checks this checkout (the agent in the project's dependencies, how production will know the release) and, with a token, what DeployAngel has seen of the app: which processes report and the release each runs, the routes, job classes, and scheduled jobs the agent reported, and setup problems with what to do about each. It doesn't load your app, so Celery Beat, django-celery-beat, django-crontab, and recurring_jobs schedules are checked from what the running agent reported. Only errors (a rejected token, an unreachable server, no agent in the dependencies) exit 5; warnings exit 0, so it's safe in CI. It reads DEPLOYANGEL_API_TOKEN, or DEPLOYANGEL_TOKEN where the app runs, so heroku run deployangel doctor also shows the release that process reports.

Output is text on a terminal and JSON when piped (--format=text|json). Exit codes: 0 cleared, 1 failed, 2 not cleared, 3 still verifying or timed out, 4 deployment not found, 5 usage, auth, or network error, 6 no problems so far at the initial check (not cleared), 7 warnings at the initial check. In GitHub Actions, verify also writes the verdict to the job's summary.

For coding agents, run deployangel install agents in the project. It adds the MCP server to .mcp.json (Claude Code), .cursor/mcp.json (Cursor), and .codex/config.toml (Codex, which reads it only in projects you trust), and instructions to wait for a verdict after deploying to AGENTS.md, with a CLAUDE.md that imports it. In a uv or Poetry project it runs deployangel through uv run or poetry run. It never replaces an existing entry, and running it again updates only its own instructions. Commit the files; the token stays in your environment.

Or add the server yourself:

claude mcp add deployangel -- deployangel mcp        # Claude Code (or: -- uvx deployangel mcp)

For Codex, in ~/.codex/config.toml:

[mcp_servers.deployangel]
command = "deployangel"     # or "uvx", with args = ["deployangel", "mcp"]
args = ["mcp"]

Any other MCP client (Cursor, VS Code, Zed, ...) runs the same command. The server needs DEPLOYANGEL_API_TOKEN in the environment it starts in.

The tools are get_verification, wait_for_verification, get_exercise_plan, list_deployments, get_exception, list_late_regressions, and register_deployment when the token allows it. None of them can change production. When a release isn't cleared yet, deployangel plan (or get_exercise_plan) says what stands between it and clearance, and what to exercise against production so it clears sooner. It separates what clearance waits on from changed and rarely used paths that are only worth running. Routes that change data are marked; use a test account for them, or ask first. deployangel exercise --url=<production URL> does the read-only part: it requests the plan's GET routes that have no path parameters, spreading any request shortfall across them (at most 200 requests, about 5 a second, as DeployAngel-Exercise), then records what it sent on the release, where the page lists it under "Exercised from your side". It skips and names routes that change data or need a path parameter, and stops requesting a page after its first 404, sending its share to the pages that answered. --dry-run shows what it would send.

The command and its output match the Ruby gem's deployangel command, so the docs and agent instructions for either apply to both.

Development

python -m venv .venv
.venv/bin/pip install -e . django djangorestframework django-celery-beat fastapi httpx flask celery rq fakeredis pytest pytest-asyncio
.venv/bin/pytest

RQ_REDIS_URL=redis://localhost:6379/15 also runs RQ's forking worker against a real Redis.

The agent speaks DeployAngel Agent Protocol v1: one gzipped JSON payload per process per minute to POST /api/v1/telemetry, and the application's metadata once per process to POST /api/v1/application_metadata. src/deployangel/core/protocol.py and src/deployangel/metadata.py build them.

Available Tools

6 tools
get_exceptionC

Sanitized details and the application stack trace for an exception fingerprint.

ParametersJSON Schema
NameRequiredDescriptionDefault
fingerprintYes

TDQS

C2.8/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 burden. It hints at a meaningful trait by saying details are 'sanitized' (i.e., redacted), but says nothing about authentication requirements, error behavior for invalid fingerprints, or whether retrieval has 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?

A single short sentence fragment with zero filler, and the return content is front-loaded. It is efficient rather than padded, though the terseness edges toward under-specification.

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 single-lookup read tool with no output schema, the description does cover the returned content (details plus stack trace). However, with no annotations and an undocumented parameter, it omits error handling, sanitization scope, and usage context that an agent would need.

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 single parameter has 0% schema description coverage, so the description is the only source of param meaning. It only restates that the fingerprint identifies an exception, adding no format, origin, or validity details beyond the parameter's own name.

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 the specific resource returned: sanitized details and the application stack trace for an exception fingerprint. It is clear what the tool retrieves, though it is a noun phrase rather than a verb+resource statement and does not distinguish itself from siblings such as get_verification or list_late_regressions.

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 call this tool versus alternatives, no prerequisites, and no indication of where a fingerprint comes from or what to do if the fingerprint is unknown. Usage must be entirely inferred from the name and description.

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

get_exercise_planA

What stands between a release and clearance, and what to exercise against production so it clears sooner: normally active routes short of their runs, routes this release changed that haven't run, and critical flows. needed marks what clearance waits on; the rest are only worth running. Routes marked mutating change data: use a test account or ask first. Your requests count as ordinary traffic; report what you ran with report_with. Defaults to the current git HEAD.

ParametersJSON Schema
NameRequiredDescriptionDefault
commitNoCommit SHA (prefix of 7+ characters is fine).
latestNoUse the most recent deployment.
versionNoRelease version, e.g. v184.
deployment_idNoDeployAngel deployment ID.

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and does meaningful work: it flags that routes marked mutating change data, that these hit production and count as ordinary traffic, and that the target defaults to the current git HEAD. It stops short of stating whether the call itself is read-only or what the plan's shape/size is.

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?

Every sentence carries information, but the phrasing is dense and indirect — the lead clause delays the actual subject, and the mutating/reporting caveats are stacked mid-paragraph. It reads as stream-of-consciousness rather than front-loaded structure.

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?

No output schema and no annotations, yet the description covers return content categories, the `needed` vs optional distinction, side-effect risk, and default resolution — enough for an agent to call it correctly. Only the precedence among the four selectors and the response format remain unstated.

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%, so 3 is the baseline; the description adds value beyond the schema by disclosing the default behavior ('Defaults to the current git HEAD'), which explains what happens when none of the four optional selectors is supplied. It does not clarify how commit/latest/version/deployment_id interact or take precedence.

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 names the resource concretely — an exercise plan enumerating active routes short of their runs, routes changed by this release that haven't run, and critical flows — plus the `needed` flag. The opening clause ('What stands between a release and clearance') is indirect, but the enumeration makes the output identifiable and differentiates it from verification-status siblings like get_verification.

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

Usage Guidelines3/5

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

It implies the workflow (run routes, then 'report what you ran with report_with') and gives a safety rule for mutating routes, but never says explicitly when to call this versus get_verification or wait_for_verification, nor any prerequisites. It also references a tool (report_with) that is not among the listed siblings, leaving the chaining ambiguous.

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

get_verificationA

Current verdict document for a deployment: state, verdict, confidence, coverage, findings, new exceptions, clearance report, and what is still watched. Defaults to the current git HEAD.

ParametersJSON Schema
NameRequiredDescriptionDefault
commitNoCommit SHA (prefix of 7+ characters is fine).
latestNoUse the most recent deployment.
versionNoRelease version, e.g. v184.
deployment_idNoDeployAngel deployment ID.

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations present, the description carries the full burden. It discloses that the call is a read-style retrieval and what the returned document contains, plus the HEAD default. It says nothing about permissions, rate limits, or how conflicting selectors (e.g. commit and version together) are resolved, leaving meaningful behavioral 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?

Two sentences, front-loaded with the resource and its contents, with the default behavior stated last. The field enumeration is dense but justified because no output schema exists to carry that information. Minimal waste overall.

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 four-optional-parameter read tool with no output schema and no annotations, the description covers what the agent most needs: what comes back and what happens with no arguments. The remaining gap is selector precedence and any auth or access requirements, which prevents a 5.

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%, so the baseline is 3. The description goes beyond the schema by stating the default selection behavior ('Defaults to the current git HEAD'), which matters because all four selector parameters are optional and the schema never explains what happens when none is supplied. That is real added meaning, though it does not explain precedence among the selectors.

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 names a specific resource ('verdict document for a deployment') and enumerates the concrete contents (state, verdict, confidence, coverage, findings, exceptions, clearance report). That is far more informative than a tautology. It stops short of explicitly distinguishing itself from the sibling 'wait_for_verification', so it lands at 4 rather than 5.

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 sentence 'Defaults to the current git HEAD' tells the agent it can call the tool with no arguments, which is genuine usage context. However, there is no statement of when to prefer this over 'wait_for_verification' or how to choose among the four selector parameters, so usage is only implied.

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

list_deploymentsC

Recent deployments with their verification state and verdict.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

C2.8/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 behavioral disclosure. It implies a read-only list operation and mentions returned fields, but does not state whether it is read-only, how results are sorted, pagination behavior, or authentication requirements.

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 concise sentence with no wasted words. It is front-loaded with the resource and returned data, though it is a noun phrase rather than a complete sentence.

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 simple list tool with one optional parameter and no output schema, the description conveys the core return content but omits the limit parameter semantics and any behavioral context. It is adequate but incomplete for an agent to know how to call it optimally.

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 schema supplies a default, maximum, and minimum, but the description adds no meaning beyond that, failing to compensate for the low coverage.

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 identifies the resource (deployments) and the returned data (verification state and verdict), making the tool's purpose clear. However, it doesn't explicitly state the verb 'list' or differentiate from siblings like list_late_regressions, so an agent must infer from the tool name.

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 list_late_regressions or get_verification. Usage is only implied by the description's focus on recent deployments.

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

list_late_regressionsC

Failures found after a release was cleared, on paths the clearance did not cover.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
sinceNoISO 8601 time

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 full burden of behavioral disclosure. It only defines the failure category and omits operational traits such as pagination behavior, auth requirements, or what the returned list contains.

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?

A single sentence with no filler, appropriately sized for a brief listing tool. It is not front-loaded with an action verb, but it wastes no words.

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 list tool with no output schema and no annotations, the description should clarify filtering, scope, and return expectations. It supplies only a domain definition and leaves the agent to infer how to call and interpret the tool.

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 coverage is 50%: 'since' is documented as an ISO 8601 time, while 'limit' has bounds but no textual description. The description never mentions either parameter, so it does not compensate for the gap.

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 defines the resource precisely: failures after a release clearance, on paths the clearance did not cover. It lacks an explicit action verb and does not distinguish from sibling tools, but the tool name supplies the verb and the description clarifies the domain concept.

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 when-to-use guidance, no prerequisites, and no alternatives are named. The agent gets no help deciding between this and siblings like list_deployments or get_exception.

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

wait_for_verificationA

Wait for a deployment's verification. until=initial returns at the 15-minute initial check ("no problems so far" is NOT clearance); until=verdict waits for verified, failed, or inconclusive. Returns the in-progress document if timeout_seconds (max 300) is reached; call again while it is still in progress. Inconclusive means not verified.

ParametersJSON Schema
NameRequiredDescriptionDefault
untilNoinitial
commitNoCommit SHA (prefix of 7+ characters is fine).
latestNoUse the most recent deployment.
versionNoRelease version, e.g. v184.
deployment_idNoDeployAngel deployment ID.
timeout_secondsNo

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the burden well: it discloses the 300-second timeout cap, that it returns the in-progress document on timeout, that the caller should re-invoke, and that 'no problems so far' is not clearance and inconclusive is not verified. Missing only whether the call blocks, and no rate-limit or auth context.

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?

Front-loaded with the core action, then four tight sentences covering mode semantics, timeout behavior, retry guidance, and the inconclusive pitfall. Every sentence carries distinct information; the parenthetical warnings are high-value rather than filler.

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 6-parameter polling tool with no annotations and no output schema, the description supplies the critical behavioral contract (timeout, retry, terminal vs non-terminal states). It could say a bit more about what a verdict result contains, but it is largely self-sufficient.

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 a moderate 67%, and the description adds genuine semantics beyond it for the until enum (initial = 15-minute check, verdict = verified/failed/inconclusive) and the timeout_seconds cap. It adds little for the commit/latest/version/deployment_id selectors, which rest on schema 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?

States a specific verb+resource: waits for a deployment's verification, with two distinct modes (initial check vs verdict). It is distinguishable from a one-shot get_verification in spirit, but the description never explicitly contrasts the two sibling tools, so sibling differentiation is left to inference.

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?

Clear operational guidance: until=initial returns at the 15-minute initial check, until=verdict waits for a terminal state, and when timeout_seconds is hit you should call again while still in progress. It stops short of saying when to prefer this over get_verification or when to skip waiting entirely.

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. 6 tool updatesv0.1.0
    • First observedget_exception
    • First observedget_exercise_plan
    • First observedget_verification
    • First observedlist_deployments
    • First observedlist_late_regressions
    • First observedwait_for_verification
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 6 tools

Disambiguation4/5

get_verification (immediate snapshot) and wait_for_verification (blocking poll) are functionally distinct, and the remaining tools target clearly separate resources: deployments list, exercise plan, exception details, and post-clearance regressions. There is mild overlap between get_verification and wait_for_verification since both return the same verdict document, but descriptions clarify the difference.

Naming Consistency5/5

All six tools follow a clean verb_noun snake_case pattern (get_*, wait_for_*, list_*), with verbs matching their action type consistently. No convention mixing.

Tool Count5/5

Six tools is well-scoped for a deployment verification/monitoring server, with each tool earning its place in the verification workflow.

Completeness4/5

Coverage is strong for the verification domain: read state, wait for verdict, plan exercises, list deployments, inspect exceptions, and track late regressions. However, the exercise-plan description references a 'report_with' tool for reporting runs that is not present, creating a minor dead end.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Jenkins MCP Server

    ooooshino
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only MCP server for Jenkins CI, enabling AI agents to securely query job/build status, logs, artifacts, and generate verification reports for loop workflows.
    17 npm
    ISC

  • jenkins-mcp

    ruslan-casafari
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides read-only access to Jenkins, enabling users to inspect project and environment build status, list builds, retrieve console logs and test reports, diagnose failed builds, and search jobs via natural language, without triggering or changing builds.
    416 npm
    MIT

  • ReleaseGuard AI

    Benighter
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables evidence-first release readiness assessment by running or accepting build, API, browser, visual, performance, and security evidence, then returning SHIP, REVIEW, or HOLD recommendations with clustered regressions.
    1 npm
    Apache 2.0

  • mcp-dotpals

    Rikinshah787
    A
    license
    A
    quality
    B
    maintenance
    Checks what local coding agents such as Claude Code, Codex and Cursor really did: files changed, commands run and test results read from test output, not the agent's word. Unclear test results can be double-checked by Laya (on your computer) or TypeSafe's Jev (cloud, your own API key). Read-only.
    2
    10
    93 npm
    53
    MIT