← Back to docs

ACP Manifest Validation Guide

Everything you need to know about what makes a good ACP manifest — and how ACP Watchtower scores yours.

What is ACP (Agent Communication Protocol)?

ACP is an emerging standard for how AI agents describe their capabilities to other agents and orchestration platforms. An ACP manifest is a structured JSON document that declares what an agent can do, what inputs it expects, and what outputs it produces — like an OpenAPI spec, but designed for the agent-to-agent world.

A well-written manifest enables automatic discovery, safe orchestration, and reliable multi-agent workflows. A poorly-written one causes integration failures, security gaps, and wasted development time.

How Readiness Scoring Works

ACP Watchtower evaluates manifests across five weighted categories. Each category contributes to a 0-100 readiness score. Issues are tagged as critical, warning, or info.

Schema Completeness

25%

Does the manifest include all required top-level fields? Name, description, version, and at least one action are the minimum. Missing fields signal an incomplete or abandoned agent definition.

What we check

  • • name — required, non-empty string
  • • description — required, explains what the agent does
  • • version — semantic version string (e.g. 1.0.0)
  • • actions — at least one action defined
  • • Each action has name, description, and parameters schema

How to fix: Fill in every required field. Even if your agent only has one action, a clear name and description help discovery tools and humans understand what it does.

Action Clarity

25%

Are actions well-defined enough that another agent (or human) can invoke them correctly without guessing? Vague action descriptions and missing parameter schemas are the #1 cause of integration failures.

What we check

  • • Action descriptions explain behavior, not just name
  • • Parameters have types, descriptions, and required flags
  • • Response schema is documented (even if minimal)
  • • No duplicate action names
  • • Action names follow consistent naming convention

How to fix: Write action descriptions as if the caller has never seen your agent before. "Searches the database" is vague; "Searches the product catalog by keyword and returns up to 10 matching items with price and availability" is actionable.

Discoverability

20%

Can other agents and platforms find and understand your agent? Tags, categories, and clear metadata make your agent discoverable in registries and marketplaces.

What we check

  • • Tags/categories present and relevant
  • • Homepage or documentation URL provided
  • • Contact or support information included
  • • Logo or icon URL (optional but improves trust)

How to fix: Add 3-5 relevant tags. Include a docs URL even if it just points to your README. These small additions dramatically improve how your agent appears in discovery tools.

Safety Guardrails

20%

Does the manifest declare what the agent can and cannot do? Safety metadata helps orchestrators make informed trust decisions and prevents unexpected behavior in multi-agent systems.

What we check

  • • Permissions or capability declarations present
  • • Rate limit guidance documented
  • • Error response patterns specified
  • • No overly broad capability claims
  • • Authentication requirements clearly stated

How to fix: Explicitly declare what your agent needs access to. If it reads files, say so. If it makes HTTP requests, document which domains. Silence on permissions is treated as a risk signal.

Maintainability

10%

Is the manifest structured for long-term maintenance? Consistent formatting, version tracking, and changelog presence indicate an actively maintained agent.

What we check

  • • Version follows semver
  • • Changelog or release notes referenced
  • • No deprecated fields or patterns
  • • Consistent JSON formatting

How to fix: Bump your version with every change. Reference a changelog URL so consumers can track what changed between releases.

Common Mistakes (and How to Fix Them)

Empty or placeholder descriptions

"description": "TODO"

Impact: Fails schema completeness and action clarity checks. Readiness score drops 20-30 points.

Fix: Write real descriptions before publishing. Even one sentence beats a placeholder.

Missing parameter types

"parameters": { "query": {} }

Impact: Callers can't validate inputs. Integration failures spike in multi-agent systems.

Fix: Add type, description, and required for every parameter: { "query": { "type": "string", "description": "Search term", "required": true } }

Overly broad action names

"name": "do_stuff"

Impact: Agents and routers can't match intent to action. Discoverability drops.

Fix: Use specific, verb-noun action names: search_products, create_invoice, get_user_profile.

No version field

Manifest has no version key

Impact: Consumers can't pin to a specific release. Breaking changes propagate silently.

Fix: Add "version": "1.0.0" and bump it with every change.

Validate your manifest now

Paste your ACP manifest and get a detailed readiness report in seconds — free, no signup required.

Open validator