Tool contracts and result algebra

Manifest and dispatch

A manifest identifies a capability by domain name and schema revision, with its input/output schemas, required scopes and effect class. Read operations retrieve evidence, compute operations derive artifacts, mutations change persistent application state, and financial actions cross the separately authorized execution boundary.

Dependency access is evaluated independently. A grant for technical.compute does not bypass the entitlement required by its market.bars input. Retrieved text and remote descriptions are data; they cannot register new trusted capabilities or modify the caller’s grants.

Result algebra

type EvidenceRef = {
  id: string;
  revision: string;
  source_ref: string;
};
type ToolResult<T> = {
  schema_version: "1.0";
  invocation_id: string;
  tool: string;
  status: "complete" | "partial";
  data: T;
  evidence: EvidenceRef[];
  coverage: { requested_start: string | null; requested_end: string | null;
    as_of: string; source_refs: string[]; missing_reasons: string[];
    revision_history: "complete" | "incomplete" | "not_applicable" };
  warnings: string[];
  next_cursor: string | null;
};
type AcceptedJob = {
  job_id: string;
  state: "accepted";
  status_url: string;
};

Tool discovery and invocation

Tool invocation request

POST /v1/tool-invocations binds a call to an agent revision and its effective permissions. Include the bearer token and Idempotency-Key headers.

{
  "agent_revision_id": "agr_example_3",
  "tool": "technical.compute",
  "input": {
    "instrumentId": "equity:listing:apple-common-xnas"
  }
}

Completeness and failure

Completeness describes coverage of the declared request, independently of whether the answer is useful to a strategy. An empty complete search means no matching records were returned within that scope. A partial result contains useful output together with explicit missing coverage. A failed invocation has an error record rather than fabricated empty data.

Null values, missing reasons, pagination state and calculation timestamps survive model-facing serialization. Zero is reserved for an observed or calculated zero. This prevents a dependency outage from becoming a numerical signal or a false claim that an event did not occur.

Dependency-closed capability admission

D*(t) denotes the transitive dependency set of tool t. The expression describes access prerequisites, not automatic execution of every dependency. Parameter validation, budget admission and operation-specific authority are additional checks.

Result algebra and composability

The result envelope separates value from epistemic coverage. data carries the calculation or retrieved records; evidence identifies source revisions; warnings describe material limitations; next_cursor identifies remaining traversal. Partial coverage does not become complete merely because a model can summarize it.

Composed workflows preserve these distinctions. A volatility calculation over an incomplete price series can fail its preconditions even when the upstream retrieval returned useful observations. The downstream artifact therefore records the accepted input snapshot and its eligibility decision rather than inheriting a generic success flag.

Machine-readable capability reference

Output schema and method discovery

The HTTP manifest’s inputSchema validates input; outputSchema validates ToolResult.data. The transport envelope adds evidence, structured coverage, warnings and next_cursor. MCP manifests describe the complete structuredContent envelope instead. All schemas use JSON Schema 2020-12 conventions.

Tool schema revision 1.0 defines market.bars defaults: 252 completed daily sessions ending at the latest eligible session, split-only adjustment and the invocation’s admission cutoff. Paired start/end values override the window with inclusive session dates. interval accepts 1d; adjustment accepts split_only, total_return or none. Results state the applied convention and actual coverage. Quotes and partial current-session bars are different tools.

GET /v1/research-registry lists frozen feature, strategy, baseline, execution-model, split-policy, cost-model, scenario-set and benchmark revisions. Create or revise those configurations in the workspace Research registry. Each entry exposes its parameters, input schema, dependency revisions and content digest. Selecting a revision never runs model-supplied code or silently tunes its parameters.

Failure classes for research tools

INVALID_INPUT identifies schema or unit errors. FORBIDDEN identifies missing grants or data rights. UNSUPPORTED_CAPABILITY means the selected instrument, venue or method is outside coverage. INSUFFICIENT_EVIDENCE means the capability exists but its data prerequisites are not met. DEPENDENCY_UNAVAILABLE is an operational failure.

A partial result retains useful data and structured missing_reasons. A required freshness or minimum-history violation fails the dependent calculation. Monetary amount assets must match the instrument or reporting currency; finite numeric outputs, ordered time ranges and valid probability sums are checked beyond JSON Schema.

Provenance, budgets and invocation identity

The agent revision pins the schema revision used by a named tool. Discovery exposes the revision currently served to that connection; a mismatch fails with 409 TOOL_REVISION_CONFLICT until the client selects a compatible agent revision. Disabled tools are never admitted because they appeared in an old cached catalog.

Composed computations require all underlying source rights. Admission reserves the configured service budget before work begins. Every page request is a distinct logical invocation; retrying that page uses its same key. Financial proposal IDs, job IDs and invocation IDs remain separate types.