AgentReady CI Gate for AI-facing APIs and MCP tools

The problem

AI agents increasingly call OpenAPI operations and MCP tools. Many of those surfaces are valid for humans but too vague, too broad, or too dangerous to expose without a pre-deployment check.

Vague tool choice

Agents can select the wrong tool when names, descriptions, and usage boundaries are unclear.

Uncontrolled side effects

Refunds, emails, deletes, exports, and publishing flows need confirmation and limits before deployment.

Weak recovery

Without clear output, status, and error behavior, agents guess instead of stopping or correcting safely.

What AgentReady checks

The scanner looks for structural risks in the contract before an agent can use it.

Destructive actions

Delete, refund, send, export, publish, and other high-impact operations.

Missing confirmation boundaries

Dangerous actions without explicit human review, preview, or approval flow.

Unbounded write actions

Amounts, quantities, limits, paths, recipients, or filters without safe constraints.

Broad file, email, and refund tools

Tools that combine too much capability or expose a scope wider than agents need.

Missing dry-run or preview

State-changing actions without a safe way to inspect the planned result first.

Sensitive data exposure

Customer, payment, authentication, or file data exposed without tight boundaries.

Unclear agent instructions

Missing when-to-use, when-not-to-use, output schema, or corrective error guidance.

CI Gate behavior

The same realistic policy was applied to each commercial bad/fixed pair: --min-score 75 --fail-on critical.

Pair	Bad	Fixed	Delta	Gate result
Refund OpenAPI	54 FAIL	84 PASS	+30	Bad blocks a money-moving action without sufficient control. Fixed passes with critical risk removed.
Email MCP	63 FAIL	90 PASS	+27	Bad blocks external sending without a safe boundary. Fixed passes with explicit confirmed sending behavior.
Files MCP	67 FAIL	84 PASS	+17	Bad blocks broad file management. Fixed passes after scoped read and confirmed delete behavior are separated.

See the full validation report in Commercial Fixture CI Gate Behavior.

CLI example

node bin/agentready.js scan openapi ./openapi.json --min-score 75 --fail-on critical

GitHub Action example

name: AgentReady

on:
  pull_request:
    paths:
      - "openapi.json"
      - "mcp-tools.json"

jobs:
  agentready:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: AgentReady OpenAPI CI gate
        uses: BACOUL/timeproofs/.github/actions/agentready@timeproofs
        with:
          type: openapi
          file: ./openapi.json
          min-score: "75"
          fail-on: critical
          out: agentready-output

The action is a repository action wrapper around the AgentReady CLI, not a Marketplace listing. For a vendored local copy inside the same repository, use uses: ./.github/actions/agentready.

agentready.json output

Each scan can produce a machine-readable readiness contract for CI, reports, and future automation.

Core fields

agentready_version
score
status
risk_counts
tools[]

Finding fields

detected_risks
rule_codes
detected_rules
recommendations

Rule codes

AR001-AR010 give teams stable vocabulary for recurring agent-readiness failures. They make findings easier to discuss in pull requests, reports, and policy reviews.

AR001 Unbounded write action

AR002 Missing confirmation boundary

AR005 Sensitive data exposure

AR007 Overbroad tool scope

AR009 Unclear agent instructions

AR010 Missing rate or scope limit

Read the full reference in AgentReady Rule Codes.

Security and trust model

AgentReady is designed for pre-deployment checks and CI-friendly artifacts, not live production interception.

1

Local-first

Scan files locally in the browser, CLI, or CI runner.

2

No live API execution

AgentReady reads contracts. It does not call production endpoints.

3

No live MCP execution

MCP tools are inspected as definitions, not invoked as live tools.

4

No LLM call required

The current checks are static and deterministic.

5

No dashboard required

Use the scanner, CLI, reports, and CI outputs without an account flow.

6

CI-friendly output

Score, status, report path, and agentready.json can be used in automation.

Limitations

TimeProofs AgentReady does not guarantee that an AI agent will never fail.

It identifies structural risks that may cause AI agents to misuse APIs, tools or MCP servers.