Contributing a Tool

Contributing a Tool

A gate is only "done" when it lands across every surface in lockstep. This is the pipeline every tool moves through — and the reason the 26 tools behave identically from REST, MCP, and both SDKs.

The bar (before writing code)

A proposal must fit the Design Principles: deterministic, offline, a single checkable question, sub-500ms, PASS/FLAG/BLOCK + certificate. If it needs a model in the decision path or asks a subjective question, it's out of scope.

The graduation pipeline

proposed → in progress → shipped. A tool is shipped only when all of these are green:

1. Contract — request/response schemas added to @agentoolbox/contracts (zod). This is the single source of truth.
2. OpenAPI — openapi.json is regenerated from the contracts (pnpm gen:openapi) and committed. CI fails if it drifts.
3. API — the endpoint consumes the contract's request schema and returns the verdict + certificate.
4. TypeScript SDK — types are z.infer'd from the contracts, so the client can't drift from the API.
5. Python SDK — generated/derived from the same OpenAPI spec.
6. MCP server — the tool is registered in agentoolbox-mcp with a clear description and input schema.
7. Website catalog — an entry in the shared tool catalog powers the site and docs pages.
8. CI — tests + typecheck across packages, plus the OpenAPI drift-guard, all pass.

Why one source of truth matters

Because the schema flows outward from @agentoolbox/contracts → OpenAPI → API + SDKs + MCP, a change is made once and every surface stays consistent. There is no hand-maintained second copy of a type to fall out of sync. This is what lets us add a tool without breaking the uniform verdict contract agents rely on.

Determinism is enforced by tests

Because gates are pure functions, every rule is covered by table-driven unit tests (the command and URL gates each ship well over a hundred cases). Reproducibility isn't a claim — it's the test suite. If a rule can't be expressed as a test with a fixed input and a fixed expected verdict, it isn't ready.

See the authoritative plan and sequencing in the Roadmap.