The drift problem
When an AWP action delegates to a sibling protocol via §5.5 (via: \"mcp\", via: \"a2a\"), the underlying protocol typically has its own description field:
- MCP tools have a
description argument in server.tool(name, description, schema, handler)
- A2A skills have a
description field on each skills[] entry of the agent card
- OpenAPI operations have
summary and description
- etc.
So the same action now has two descriptions:
- AWP action
description (in agent.json)
- The protocol's native description (in MCP tool registration / A2A agent card / etc.)
Today the spec is silent on which is authoritative or whether they must match. Result: they drift.
Concrete example
laclawclaw.com just spent an evening recovering from this exact drift:
- AWP manifest declared
create_payment_link with no description
- MCP tool description said "Generate a Stripe payment link for the LaClawClaw Founders Edition $1 pre-order" (stale)
- A2A skill description said "Create a payment URL the agent hands to its human..."
- Stripe link itself charged $10
An agent reading the MCP tool description told its human "$1", but the actual Stripe page charged $10. Fix required updating two strings in the MCP+A2A code; AWP was silent and gave no signal.
Proposed clarification (v0.3)
Add to §5.5 or §9:
When an action has a via field, the named protocol's native description for that operation (e.g. MCP tool description, A2A skill description) is the source of truth for human-language semantics. Agents SHOULD prefer the protocol's native description over the AWP description. AWP description, if present, MUST be consistent with the protocol's. Implementations are encouraged to generate one from the other to prevent drift.
Or alternatively:
When via is set, AWP description becomes optional. Agents that need a description SHOULD fetch it from the named protocol's discovery surface (e.g. MCP tools/list, A2A agent-card).
The second is simpler and removes the duplication-drift problem entirely.
The drift problem
When an AWP action delegates to a sibling protocol via §5.5 (
via: \"mcp\",via: \"a2a\"), the underlying protocol typically has its own description field:descriptionargument inserver.tool(name, description, schema, handler)descriptionfield on eachskills[]entry of the agent cardsummaryanddescriptionSo the same action now has two descriptions:
description(in agent.json)Today the spec is silent on which is authoritative or whether they must match. Result: they drift.
Concrete example
laclawclaw.com just spent an evening recovering from this exact drift:
create_payment_linkwith no descriptionAn agent reading the MCP tool description told its human "$1", but the actual Stripe page charged $10. Fix required updating two strings in the MCP+A2A code; AWP was silent and gave no signal.
Proposed clarification (v0.3)
Add to §5.5 or §9:
Or alternatively:
The second is simpler and removes the duplication-drift problem entirely.