Observation
§5.5 shows A2A getting a sibling discovery URL via agent_card:
```json
"a2a": {
"version": "0.3",
"endpoint": "https://agent.example.com/agent/message\",
"agent_card": "https://agent.example.com/.well-known/agent-card.json\"
}
```
The agent_card URL points to A2A's own discovery doc, which carries per-skill descriptions, examples, schemas, etc. — richer than what fits in AWP.
This is a useful pattern: AWP says who speaks the protocol, the protocol's own discovery doc says what specifically they expose. But the spec only blesses it for A2A.
The same need exists for MCP (and others)
- MCP servers expose
tools/list which returns full tool descriptions + JSON schemas. There's no widely-adopted public URL for it (tools/list is a JSON-RPC call requiring a session), but some servers ship a static tools.json alongside.
- OpenAPI surfaces typically have a
spec_url for the OpenAPI JSON.
- GraphQL surfaces have introspection or
schema.graphql.
Today, surfaces that want to point at these have to invent a field name. laclawclaw added nothing for MCP; the agent has to call tools/list post-handshake to discover what's there.
Proposed addition (v0.3)
Bless a generic discovery field on every protocol entry, with conventional sub-fields when the protocol has a well-known discovery doc:
```json
"protocols": {
"mcp": {
"version": "2025-06-18",
"endpoint": "https://agent.example.com/mcp\",
"transport": "http",
"discovery": "https://agent.example.com/mcp/tools.json\"
},
"openapi": {
"version": "3.1",
"endpoint": "https://api.example.com\",
"discovery": "https://api.example.com/openapi.json\"
}
}
```
And rename a2a.agent_card to a2a.discovery for consistency (keep agent_card as a deprecated alias for one version).
This gives agents one consistent place to look for richer per-protocol metadata without having to know each protocol's idiosyncratic field name.
Lower priority than the other four spec issues I've filed today — this is additive rather than fixing a correctness issue.
Observation
§5.5 shows A2A getting a sibling discovery URL via
agent_card:```json
"a2a": {
"version": "0.3",
"endpoint": "https://agent.example.com/agent/message\",
"agent_card": "https://agent.example.com/.well-known/agent-card.json\"
}
```
The
agent_cardURL points to A2A's own discovery doc, which carries per-skill descriptions, examples, schemas, etc. — richer than what fits in AWP.This is a useful pattern: AWP says who speaks the protocol, the protocol's own discovery doc says what specifically they expose. But the spec only blesses it for A2A.
The same need exists for MCP (and others)
tools/listwhich returns full tool descriptions + JSON schemas. There's no widely-adopted public URL for it (tools/listis a JSON-RPC call requiring a session), but some servers ship a statictools.jsonalongside.spec_urlfor the OpenAPI JSON.schema.graphql.Today, surfaces that want to point at these have to invent a field name. laclawclaw added nothing for MCP; the agent has to call
tools/listpost-handshake to discover what's there.Proposed addition (v0.3)
Bless a generic
discoveryfield on every protocol entry, with conventional sub-fields when the protocol has a well-known discovery doc:```json
"protocols": {
"mcp": {
"version": "2025-06-18",
"endpoint": "https://agent.example.com/mcp\",
"transport": "http",
"discovery": "https://agent.example.com/mcp/tools.json\"
},
"openapi": {
"version": "3.1",
"endpoint": "https://api.example.com\",
"discovery": "https://api.example.com/openapi.json\"
}
}
```
And rename
a2a.agent_cardtoa2a.discoveryfor consistency (keepagent_cardas a deprecated alias for one version).This gives agents one consistent place to look for richer per-protocol metadata without having to know each protocol's idiosyncratic field name.
Lower priority than the other four spec issues I've filed today — this is additive rather than fixing a correctness issue.