[EPIC] D: Agent-First Programmatic API

## Problem / User Value

AI agents and automation tools need stable, documented programmatic interfaces to discover, check, and install Azure tools. Without versioned JSON schemas and MCP tool definitions, agent integrations are fragile — any output format change breaks them silently. A first-class agent API enables AI-assisted developer environment setup.

## Definition of Done

All `azd tool` subcommands produce versioned JSON via `--output json` with consistent field names and types. Four MCP tools registered (`azd_tool_list`, `azd_tool_show`, `azd_tool_check`, `azd_tool_install`) and discoverable via azd's MCP server. Agent-oriented API documentation published.

## Tasks

- [ ] **D-1: Define and document stable JSON output schemas** (M) — Audit all JSON output from A-6 through A-9 for consistency (field names, types, enums). Add `apiVersion` field to all JSON output. Document schemas in `docs/design/azd-tool/json-schemas.md` with field contracts. Define deprecation policy: fields can be added but not removed without one major version of notice.
- AC: Consistent field names/types across all commands; schema documentation published with types, enums, nullability, examples; `apiVersion` present in all JSON; deprecation policy documented; unit tests verify output matches schema
- [ ] **D-2: Implement MCP tool definitions (list, show, check, install)** (M) — Create four MCP tools in `internal/mcp/tools/`: `azd_tool_list`, `azd_tool_show`, `azd_tool_check`, `azd_tool_install` following `server.ServerTool` pattern. Read-only tools (list/show/check) annotated ReadOnly+Idempotent. Install annotated Idempotent but NOT ReadOnly. Error contract: `mcp.NewToolResultError` for validation, `mcp.NewToolResultText` for operational errors.
- AC: Four MCP tools registered and discoverable; correct annotations; error contract follows existing patterns; JSON output matches D-1 schemas; unit tests per handler
- [ ] **D-3: Write agent-oriented API documentation** (S) — Create `docs/design/azd-tool/agent-api.md` documenting all MCP tool signatures, JSON schema references, error code catalog, idempotency guarantees. Include example agent workflow for "check all tools and install missing ones."
- AC: Documentation covers all MCP tools; JSON schema examples per command; error code catalog with remediation; idempotency guarantees documented; example workflow included

## Sequencing

```
D-1 ──> D-2 ──> D-3
```

Strictly sequential — schemas must be defined before MCP tools are built, and both must exist before docs.

## Dependencies

- **Epic A (Core Engine):** A-6, A-7, A-8, A-9 must be complete — D-1 audits their JSON output; A-5 is needed for D-2's MCP handlers
- Can run **in parallel with Epic B** (Phase 2)

## Discussion Traceability

| Discussion Item | Task |
|---|---|
| F8 (agent API) | D-1, D-2, D-3 |

## Design References

- `docs/design/azd-tool/plan.md` — Phase 2b
- `docs/design/azd-tool-architecture.md` — §8.1–8.4 (MCP tool definitions)
- `docs/design/azd-tool/todos.md` — detailed acceptance criteria