improve: add usage examples to projections/predicates field descriptions in Intent types

[mchades]

Problem

When using ADP via MCP (e.g. adp-mcp), AI agents can see the full inputSchema of MCP tools at call time. The Intent Pydantic models are now used directly as MCP tool parameter types, so their JSON Schema is surfaced verbatim to agents.

The adp_describe response includes a usageContract.capabilities.projections array of ProjectionCapability objects in this shape:

{ "fieldId": "user_id" }

However, QueryIntent.projections and LookupIntent.projections expect a plain list of field ID strings:

projections: list[str] | None

Agents reading the describe response and then constructing an intent tend to copy the ProjectionCapability object format directly into projections, producing:

{ "projections": [{"fieldId": "user_id"}, {"fieldId": "name"}] }

instead of the correct:

{ "projections": ["user_id", "name"] }

Although the JSON Schema already encodes items: {type: "string"}, the current description of projections ("Fields to project.") does not clarify the relationship to the describe response, so agents reliably make this mistake.

A similar risk exists for predicates: the describe response returns usageContract.capabilities.predicates as PredicateCapability objects (with fieldId, usage, operators), which is structurally different from the Predicate / PredicateGroup expected in the intent.

Proposed Fix

Update the description strings in adp_sdk/types/intents.py (and propagate to the ADP spec) to include a concrete example and a note disambiguating the intent format from the describe-response format:

QueryIntent.projections (and LookupIntent.projections):

projections: list[str] | None = Field(
    default=None,
    description=(
        'Field IDs to include in results, e.g. ["user_id", "name"]. '
        'Pass the fieldId string values from usageContract.fields — '
        'not the ProjectionCapability objects from usageContract.capabilities.projections.'
    ),
)

QueryIntent.predicates / ReviseIntent.predicates:

predicates: PredicateExpression = Field(
    description=(
        'Filter expression. Use a single Predicate {"fieldId": "x", "op": "EQ", "value": "v"} '
        'or a PredicateGroup {"op": "AND", "predicates": [...]}. '
        'Valid operators are listed in the PredicateCapability objects returned by adp_describe.'
    ),
)

Context

This follows standard MCP tool description best practices — mainstream MCP servers (GitHub MCP, MCP Filesystem) routinely include e.g. examples in field description strings to disambiguate formats that are structurally similar but semantically different.

This is a spec-level change (the descriptions should be reflected in the ADP protocol specification) as well as a code change in this SDK.

Scope

• src/adp_sdk/types/intents.py — QueryIntent.projections, LookupIntent.projections, QueryIntent.predicates, ReviseIntent.predicates
• ADP protocol spec — update field descriptions accordingly