Define canonical server-side tool declaration contract

[chubes4]

Problem

Agents API has strong contracts for runtime client tools and mediated execution, but the generic declaration validator is still centered on client/* run-scoped tools. Downstream products now use the mediated loop for server-side ability-backed and product-local tools, but those declarations are normalized more loosely through source registries and host adapters.

That leaves a subtle boundary gap: Data Machine can mediate server tools through Agents API, but the substrate does not yet define the full canonical declaration shape for non-client executors.

Desired outcome

Agents API should define a product-neutral server-side tool declaration contract that can represent tools executed by a host adapter without encoding Data Machine-specific concepts.

Possible shape:

• support executor values such as server or host in addition to client;
• preserve existing client/* runtime tool validation rules;
• normalize common fields: name, source, description, parameters, executor, scope, runtime, and optional linked ability metadata;
• keep concrete execution mapping in the host-owned WP_Agent_Tool_Executor adapter;
• document which fields are canonical substrate fields vs host extension metadata.

Acceptance criteria

• Server-side mediated tools have a documented declaration contract in Agents API.
• Runtime client tools keep their stricter client/*, executor=client, scope=run constraints.
• The mediated loop can accept declarations normalized through the canonical substrate helper.
• Data Machine can remove any declaration-shape assumptions that only exist because server tools are currently loosely normalized.
• Smoke tests cover client runtime declarations and server/host declarations separately.

Related

• Agents API convergence umbrella: Convergence audit: merge parallel WordPress agents-api extractions #77
• Data Machine mediation migration: Migrate conversation tool execution to Agents API mediation Extra-Chill/data-machine#2453
• Data Machine mediated PR: Mediate conversation tools through Agents API Extra-Chill/data-machine#2476
• Data Machine ability projection helper: Expose ability tool projection helper Extra-Chill/data-machine#2475

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (openai/gpt-5.5)
• Used for: Boundary audit across Agents API, Data Machine, and Data Machine Code; drafted this tracker for human review.