Agent-Ready API / MCP Readiness Demo

Generated: 2026-05-18 10:20 CST

A self-contained markdown demo package for evaluating whether a public OpenAPI spec is ready to become reliable agent tools or MCP tools.

This package is intentionally static and manual. It has no forms, scripts, analytics, payment flow, account setup, private API upload, credentials, or customer-data intake.

Who it helps

• API documentation teams that want their public OpenAPI specs to be easier for AI agents and MCP wrappers to use.
• Agent/MCP builders deciding which endpoints are well-bounded and clear enough to expose as tools.
• Developer-tool reviewers who need a lightweight readiness screen before building a generator, wrapper, or linter.

Core idea

OpenAPI-valid does not mean agent-ready.

A spec can generate SDKs and still confuse an agent if it lacks:

• clear operation names,
• unambiguous input schemas,
• request/response examples,
• error recovery guidance,
• auth/rate-limit notes,
• side-effect labels,
• wrapper guardrails for mutating operations,
• selection rules for overlapping endpoints.

This demo checks documentation and agent usability only. It does not test live endpoint behavior.

Package contents

• checklist.md — a 6-point manual readiness checklist and scoring rubric.
• example-report.md — synthetic/public-style example output with a compact scorecard and wrapper recommendations.
• publication-readiness.md — review notes for possible GitLab Pages or Cloudflare Pages static publication.

How to use it manually

1. Pick a public OpenAPI spec or a synthetic fixture. Do not use private customer specs for this demo.
2. Read the spec without calling live endpoints.
3. Score each checklist area from 0 to 2.
4. Record the strongest agent-readiness signals.
5. Record the biggest MCP/tool-use risks.
6. Recommend a small wrapper surface: usually read-only endpoints first, with mutating operations hidden or confirmation-gated.
7. Label the output as documentation/usability review only.

What this does not do

This is not:

• a security audit,
• a compliance audit,
• legal advice,
• API quality certification,
• uptime or reliability testing,
• vulnerability scanning,
• private API handling,
• a promise that an API is safe for production agent use.

Do not claim an API is “certified”, “safe”, “secure”, “compliant”, or “production-ready” based on this package.

Source basis

This package condenses prior internal work from:

• t_a396c0e0: public OpenAPI readiness analysis using Swagger Petstore and weather.gov examples.
• t_29ce9c25: compact 6-point readiness demo and synthetic OpenAPI example.
• t_fa0d9efc: public-facing copy pack and risk-boundary wording.

No private specs, credentials, customer data, or live security/compliance checks are included.

Recommendation

GO, with review gate.

Reason: this is a low-risk, static, developer-tool artifact that can become a Venture mainline experiment as a public checklist/demo before any automation or service offer. The strongest wedge is not “another OpenAPI linter”; it is the agent/MCP wrapper-readiness lens: tool selection, examples, side-effect labeling, error recovery, and wrapper guardrails.

Next action: reviewer checks copy-risk boundaries, then Builder can convert this markdown pack into a static page if approved.

6-Point Agent/API/MCP Readiness Checklist

Purpose: evaluate whether a public OpenAPI spec can be manually reviewed for agent-tool or MCP-wrapper readiness.

Scope: documentation and agent usability only. Not security, privacy, compliance, legal, uptime, vulnerability, or production certification review.

Scoring

Score each area from 0 to 2:

• 2 = strong: explicit, machine-readable where relevant, low ambiguity.
• 1 = partial: present but incomplete, ambiguous, or needs wrapper curation.
• 0 = weak/missing: likely to cause wrong tool selection, invalid inputs, unsafe retries, or unexpected side effects.

Readiness bands:

• 10-12: strong candidate for a narrow MCP/tool wrapper after human review.
• 7-9: demo or internal prototype candidate; add wrapper guardrails before production use.
• 0-6: not agent-ready without documentation/schema cleanup.

1. Tool identity and operation naming

Check:

• Stable operationId, route names, command names, or MCP tool names exist.
• Names are specific action/object labels, not generic handlers.
• Similar operations are distinguishable without reading long documentation.
• Read-only and mutating operations are visibly different.

Strong examples:

• get_current_weather_by_coordinates
• list_orders
• cancel_order_by_id

Weak examples:

• getData
• submit
• handler
• doThing

Wrapper implication: if names cannot be generated directly, add a curated naming layer before exposing tools to agents.

2. Input schema clarity

Check:

• Required vs optional inputs are explicit.
• Path/query/body/header distinctions are clear.
• Types, ranges, enums, defaults, units, locale, time zone, currency, and date formats are documented.
• IDs and names are not confused.
• Polymorphic inputs use clear oneOf / anyOf guidance or discriminators.

Strong example:

• latitude is a number from -90 to 90.
• longitude is a number from -180 to 180.
• units is metric | imperial and defaults to metric.

Weak example:

• location is a free string with no accepted format.

Wrapper implication: tool inputs should map cleanly to JSON Schema. If the agent must infer units or hidden defaults, the wrapper should add them.

3. Output and error contract

Check:

• Successful responses have schemas and examples.
• Error responses have schemas or at least clear descriptions.
• 4xx user-fixable errors are separated from 5xx transient upstream failures.
• Retryable vs non-retryable outcomes are documented.
• Empty, binary, and file responses are intentionally labeled.

Strong examples:

• 400 invalid_coordinates: fix latitude/longitude and retry.
• 404 region_not_found: ask user for a different region.
• 429 rate_limited: retry after the Retry-After header.

Weak example:

• All failures return an undocumented message string.

Wrapper implication: translate raw API errors into short actionable tool errors such as invalid_input, not_found, rate_limited, or temporary_upstream_failure.

4. Action safety and side-effect labeling

Check:

• Read-only vs mutating operations are obvious.
• External side effects are named: sends email, charges card, deletes record, posts message, changes permissions, creates account, or triggers workflow.
• Idempotency is documented where relevant.
• Confirmation requirements are clear for writes/deletes/payments/notifications.

Strong example:

• create_weather_alert_subscription says it sends a confirmation email and requires user-provided email.

Weak example:

• update could change anything and gives no side-effect detail.

Wrapper implication: expose read-only tools first. Mutating tools need guardrails, explicit confirmation, dry-run behavior, or default-disable treatment.

5. Usage constraints and policy hints

Check:

• Auth scheme, scopes, API key/header names, and public/no-auth status are clear.
• Rate limits, pagination limits, backoff behavior, and retry policies are documented.
• Required headers such as User-Agent or contact fields are explained.
• Credential availability is not left for the agent to invent.

Strong example:

• A public endpoint states no credentials are required and documents 429 behavior.

Weak example:

• Docs mention “contact us for access” but the spec has no auth scheme or rate-limit notes.

Wrapper implication: put credentials, headers, rate-limit handling, and policy constraints in the wrapper configuration rather than making the agent guess.

6. Example coverage and recovery paths

Check:

• Realistic request examples exist for important operations.
• Response examples exist for common success cases.
• Edge cases cover empty results, invalid inputs, pagination, enums, date ranges, and nested payloads.
• Docs explain what the caller should try next after common failures.

Strong example:

• Current-weather endpoint has valid coordinate request, example response, invalid-coordinate example, and rate-limit recovery note.

Weak example:

• No examples; agent must infer valid payloads from schemas and prose.

Wrapper implication: examples become tool descriptions, tests, eval fixtures, and recovery prompts. Missing examples are usually the cheapest readiness gap to fix.

Minimal audit template

For each reviewed API/spec, record:

• Source: public spec URL or synthetic fixture name.
• Review date.
• Scope note: documentation/usability only; no security/compliance guarantee.
• Score for each of the 6 checks.
• Total score and readiness band.
• Top 3 strengths.
• Top 3 agent/tool-use risks.
• Suggested wrapper surface: which tools to expose first.
• Guardrails: hidden defaults, validation, confirmation requirements, examples to add.
• Overall recommendation: strong candidate, demo/prototype only, or not agent-ready.

Example Report: Tiny Weather Demo API Agent/MCP Readiness

Review date: 2026-05-18

Source: synthetic public-style OpenAPI fixture, not a real service.

Scope: documentation and agent usability review only. This example does not call live endpoints, handle credentials, analyze private APIs, perform security scanning, or make compliance claims.

Synthetic API summary

Tiny Weather Demo API has two operations:

1. getCurrentWeatherByCoordinates

- Method: GET /weather/current

- Type: read-only

- Purpose: return current weather for one latitude/longitude point.

1. createWeatherAlertSubscription

- Method: POST /alerts/subscriptions

- Type: mutating / external side effect

- Purpose: create an email subscription and send a confirmation email.

This deliberately includes one low-risk read-only operation and one operation that requires guardrails.

Example OpenAPI excerpt

openapi: 3.1.0
info:
  title: Tiny Weather Demo API
  version: 0.1.0
paths:
  /weather/current:
    get:
      operationId: getCurrentWeatherByCoordinates
      summary: Get current weather for one latitude/longitude point.
      description: Use for current conditions only. Do not use for forecasts or historical weather.
      parameters:
        - name: latitude
          in: query
          required: true
          description: Decimal degrees, -90 to 90.
          schema: { type: number, minimum: -90, maximum: 90 }
          example: 37.7749
        - name: longitude
          in: query
          required: true
          description: Decimal degrees, -180 to 180.
          schema: { type: number, minimum: -180, maximum: 180 }
          example: -122.4194
        - name: units
          in: query
          required: false
          description: Unit system for temperature and wind speed. Defaults to metric.
          schema: { type: string, enum: [metric, imperial], default: metric }
      responses:
        '200':
          description: Current observed weather at the requested point.
        '400':
          description: Invalid coordinate or units value. Fix the input and retry.
        '429':
          description: Rate limit exceeded. Retry after the Retry-After header.
  /alerts/subscriptions:
    post:
      operationId: createWeatherAlertSubscription
      summary: Create an email subscription for severe-weather alerts.
      description: Mutating operation. Sends confirmation email to the requested address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, region_code]
              properties:
                email: { type: string, format: email }
                region_code: { type: string, description: Public region code, e.g. CA-SF. }
                min_severity: { type: string, enum: [watch, warning], default: warning }
      responses:
        '201':
          description: Subscription created; confirmation email sent.
        '400':
          description: Invalid email, region, or severity. Fix input and retry.
        '409':
          description: Subscription already exists. Do not create another.

Scorecard

| Check | Score | Notes |

|---|---:|---|

| 1. Tool identity and operation naming | 2 | Operation IDs are specific and action/object oriented. Current weather and subscription creation are easy to distinguish. |

| 2. Input schema clarity | 2 | Required fields, coordinate ranges, enums, defaults, email format, and examples are present. |

| 3. Output and error contract | 1 | Basic 200/201/400/409/429 descriptions exist, but structured success/error response schemas and full examples are incomplete. |

| 4. Action safety and side-effect labeling | 2 | The subscription endpoint is clearly mutating and says it sends a confirmation email. |

| 5. Usage constraints and policy hints | 1 | Rate-limit response is mentioned, but global quotas, auth/no-auth policy, and user-agent requirements are absent. |

| 6. Example coverage and recovery paths | 1 | Parameter examples exist, but full request/response examples and edge-case examples are incomplete. |

Total: 9 / 12.

Readiness band: demo or internal prototype candidate; add wrapper guardrails before production use.

Top strengths

1. Operation names are specific enough to become MCP tool names with light editing.
2. Inputs include ranges, enums, defaults, and required-field markers.
3. The mutating operation names its side effect instead of hiding it behind a vague action.

Top agent/tool-use risks

1. Missing structured response examples make it harder to generate tests or tool-use evals.
2. Rate-limit behavior is only partly described.
3. The subscription endpoint could send email; it should not be exposed without explicit user confirmation.

Suggested MCP wrapper surface

Expose first:

get_current_weather_by_coordinates

Tool description:

Get current observed weather for one latitude/longitude point. Use only for current conditions, not forecasts or history. Inputs are decimal latitude -90..90, longitude -180..180, and optional units metric|imperial defaulting to metric.

Wrapper guardrails:

• validate coordinate bounds before calling the API,
• default units to metric,
• return invalid_coordinates for local validation failure,
• return rate_limited and surface retry-after when available.

Do not expose by default:

create_weather_alert_subscription

If exposed later, require:

• explicit user confirmation,
• user-provided email only; never infer email address,
• visible notice that confirmation email will be sent,
• de-duplication handling for 409,
• clear environment policy for whether the tool is allowed to send external emails.

Improvements before production wrapper use

• Add full 200 and 201 response schemas.
• Add example 200 current-weather response.
• Add example 400 invalid-coordinate response.
• Add explicit public/no-auth or auth requirement.
• Add global rate-limit/backoff policy.
• Add wrapper tests from the examples.

Overall recommendation for this example

Demo-ready with curation.

It is suitable for teaching the agent-readiness lens and for a static public artifact. It is not enough to justify an automatic production MCP server without additional examples, response schemas, policy notes, and guardrails for mutating operations.

Publication Readiness Note

Package: Agent-Ready API / MCP Readiness Demo

Prepared: 2026-05-18 10:20 CST

Publication recommendation

GO, after reviewer gate.

This should become a Venture mainline candidate as a static developer-tool artifact, not as a SaaS scanner or paid audit yet.

Why GO:

• The artifact is self-contained markdown.
• It uses synthetic/public-style OpenAPI information only.
• It does not require accounts, credentials, private API specs, customer data, payments, or deployment-side storage.
• The value proposition is specific: agent/MCP readiness from a documentation and wrapper-usability lens.
• It can be published as a static page and evaluated by audience reaction before building automation.

Required reviewer checks before publication

A reviewer should confirm that the final page:

• does not claim security, privacy, compliance, legal, uptime, or production certification coverage;
• does not say any API is safe, certified, compliant, or production-ready;
• does not invite users to upload private specs, API keys, tokens, internal docs, or customer data;
• contains no forms, analytics, trackers, cookies, payment links, account registration, or outbound customer intake;
• clearly states: documentation and agent-usability review for public/synthetic OpenAPI specs only;
• keeps calls to action artifact-navigation only, such as “read the checklist” or “compare your public spec manually”.

Static deployment shape

Suitable low-risk options after approval:

1. GitLab Pages

- Commit this markdown package into a static site repo.

- Render with plain markdown, a static-site generator, or hand-written HTML.

- Keep repo/page public only after reviewer approval.

1. Cloudflare Pages

- Use a static directory with no server functions.

- No analytics, forms, workers, server-side logging additions, or customer intake.

- Publish only after reviewer approval.

Do not deploy from this task. Deployment requires a separate explicit approval/card.

Suggested page structure

1. Hero

- “Is your OpenAPI spec ready for agents?”

- Boundary sentence near the top.

1. Problem

- OpenAPI-valid does not mean agent-ready.

- Common MCP/tool-use failures: wrong tool, wrong input, missing examples, unsafe writes, unclear recovery.

1. Checklist preview

- Six readiness areas.

- 0-2 scoring.

- readiness bands.

1. Worked example

- Tiny Weather Demo API synthetic scorecard.

- Read-only tool vs mutating tool contrast.

1. Wrapper recommendations

- expose small read-only surface first,

- add validation and hidden defaults,

- confirmation-gate mutating/external-side-effect tools,

- use examples as eval fixtures.

1. Boundaries

- no private API intake,

- no credentials,

- no security/compliance/legal/certification claims,

- no live endpoint testing.

1. Conservative CTA

- Read the checklist.

- Review the example report.

- Use it as an internal worksheet for public specs.

Conservative CTA copy

Allowed:

• Read the checklist
• Review the example report
• Use this as an internal readiness worksheet
• Compare a public spec manually
• Review wrapper recommendations

Avoid:

• Submit your API
• Upload your OpenAPI spec
• Get an audit
• Book a call
• Enter your email
• Start paid scan
• Connect GitHub
• Add API key

Mainline decision

Recommendation: GO.

Mainline hypothesis:

Developers and API teams need a practical way to decide whether public OpenAPI specs can be converted into reliable agent/MCP tools. A static checklist plus worked example is enough to test interest without cost, private data risk, or overbuilding.

Next action:

Assign a reviewer gate for copy-risk and claims review. If approved, create a separate builder card to convert this markdown package into a static page for GitLab Pages or Cloudflare Pages. Do not add forms, analytics, deployment, outreach, payments, or customer intake without Cly confirmation.