# Agent Tool Specification Auditor (`bmiller1009/agent-tool-specification-auditor`) Actor

Audit OpenAPI™ 3.0 and 3.1 API descriptions for agent-tool readiness, operation risk, schema quality, and safety gaps.

- **URL**: https://apify.com/bmiller1009/agent-tool-specification-auditor.md
- **Developed by:** [Sentinel Signal](https://apify.com/bmiller1009) (community)
- **Categories:** Developer tools, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$40.00 / 1,000 openapi audits

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Agent Tool Specification Auditor

Agent Tool Specification Auditor performs a deterministic review of an OpenAPI™ 3.0 or 3.1 API description. It is designed for teams deciding whether an API description is clear, bounded, and safe enough to expose as agent tools. The Actor does not use an LLM and never invokes any operation described by the document.

OpenAPI is a trademark of The Linux Foundation. This independent project is not affiliated with or endorsed by the OpenAPI Initiative or The Linux Foundation.

### Input

Supply exactly one source: an inline JSON `document`, inline `yaml`, or a public HTTPS `sourceUrl`. Remote documents are limited to 5 MiB and are retrieved only from public HTTPS port 443 with DNS pinning and redirect revalidation.

```json
{
  "document": {
    "openapi": "3.1.0",
    "info": {"title": "Example API", "version": "1.0.0"},
    "paths": {
      "/health": {
        "get": {
          "operationId": "getHealth",
          "responses": {"204": {"description": "Healthy"}}
        }
      }
    }
  }
}
```

### Analysis and output

The analyzer inventories read, write, and destructive operations; reviews operation IDs, descriptions, request and response schemas, examples, authentication declarations, and common unbounded schema shapes; and calculates an overall readiness result. Internal JSON references are resolved. External references are reported as findings and never fetched.

The default dataset receives one stable API-IFY result envelope. Findings contain rule IDs, severities, messages, and JSON Pointer evidence paths. Traversal depth, object count, reference expansion, and output findings are bounded. Cyclic object graphs, duplicate YAML keys, malformed component shapes, and documents exceeding those limits return explicit uncharged failures rather than exhausting the process. The `RUN_SUMMARY` key-value-store record reports status, bytes, HTTP activity, duration, and billing.

A successful audit produces a result projection like this:

```json
{
  "status": "success",
  "result": {
    "openapiVersion": "3.1.0",
    "overallReadiness": "ready",
    "riskCounts": {"read": 1, "write": 1, "destructive": 0},
    "findingCounts": {"high": 0, "medium": 0, "low": 2}
  }
}
```

See [`examples/sample-input.json`](examples/sample-input.json) and [`examples/sample-output.json`](examples/sample-output.json) for complete schema-valid contracts. No source is prefilled because users must intentionally choose exactly one input form.

### Pricing

A successfully delivered deterministic audit charges one `openapi-audit` event. Invalid inputs, unsafe targets, unreachable documents, unsupported formats, and analyzer failures are uncharged. The Actor checks the remaining event budget before fetching or analyzing the document. The current event price is displayed by Apify.

### Privacy and security

Inline documents are processed in memory. Remote retrieval never follows a redirect without rechecking the destination. Described operations are never called, and external `$ref` targets are never fetched. Published output is sanitized for authorization values, API keys, tokens, passwords, secrets, private keys, and sensitive URL query parameters. API-IFY operates no separate database for this Actor.

### Operations and support

Use Apify schedules to audit a specification after releases, and consume results through the dataset API or integrations. When requesting support through Apify Issues, provide the run ID and result `itemId` without attaching confidential specifications or credentials.

# Actor input Schema

## `document` (type: `object`):

An inline OpenAPI 3.0 or 3.1 document. Use exactly one input source.

## `yaml` (type: `string`):

An inline UTF-8 OpenAPI YAML document. Use exactly one input source.

## `sourceUrl` (type: `string`):

A public HTTPS URL serving OpenAPI JSON or YAML. Use exactly one input source.

## Actor input object example

```json
{}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("bmiller1009/agent-tool-specification-auditor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("bmiller1009/agent-tool-specification-auditor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call bmiller1009/agent-tool-specification-auditor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bmiller1009/agent-tool-specification-auditor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bKXgW9po22gLCP5dr/builds/94UYsDUlXBHX2uNbr/openapi.json