Adopt Touba From Existing Tools

Touba does not require teams to rewrite an existing agentic stack. The recommended adoption path is to keep useful integrations, then place them under Touba contracts: .tb source, AIR, manifest, opaque secrets, budgets, human approval when the effect requires it, handler and traces.

The main shift is simple: a tool is no longer only exposed to a model; it becomes a declared, reviewable and observable capability.

Entry Paths

You already have	Touba entry
an MCP server	import its tools as governed Touba tool declarations
a LangChain @tool function	declare the contract in .tb, keep the body in a handler
an OpenAI function-calling schema	turn the JSON Schema into Touba types and manifest entries
a REST or OpenAPI API	generate a tool, manifest and bounded HTTP handler
a useful local script	store it in a skill pack, then expose it through a tool if execution is needed

MCP To Touba

MCP exposes tools through tools/list, then executes them through tools/call. An MCP tool carries a name, description, JSON Schema inputSchema and sometimes an outputSchema. That is enough information to produce an initial Touba contract. Reference: MCP Tools specification.

MCP	Touba
Tool.name	tool name and canonical ref
Tool.description	tool and handler documentation
inputSchema	Touba type used by takes
outputSchema or structuredContent	Touba type used by gives
text result	bounded Text field or declared resource
tools/call	Touba handler that calls the MCP server
server authentication	secret handle declared in the manifest
sensitive operation	human.approve before the effect
timeout or rate limit	Touba budget and handler timeout
execution observation	Touba trace

The touba mcp import command reduces that adoption friction. It consumes an explicit MCP tools snapshot and produces the corresponding Touba contract: .tb source, manifest fragment, stdio bridge config, bridge handlers, secrets template, import report, and local README.

Terminal

touba mcp import mcp.github.json \
  --module integrations.mcp.github \
  --out integrations/github \
  --mode plan

plan mode lets developers review names, types, grants, and secret handles before writing files. write creates the files; check verifies that generated artifacts have not drifted. MCP tools that cannot produce a clear Touba contract are listed in the refusal report with the reason.

After generation, mcp.bridge.config.json points to the approved local MCP server to launch over stdio and maps its environment variables to granted secret handles. Secret values stay in the Touba store or execution environment, never in that file.

Minimal MCP Example

mcp.github.json

{
  "mcp_import_config_version": "touba-mcp-import-config-v1",
  "server": {
    "name": "github",
    "transport": "snapshot",
    "secret_handles": ["GITHUB_TOKEN"],
    "timeout_ms": 5000,
    "max_payload_bytes": 65536
  },
  "tools": [
    {
      "name": "post_comment",
      "description": "Post a GitHub comment after review",
      "secret_handles": ["GITHUB_TOKEN"],
      "inputSchema": {
        "type": "object",
        "properties": {
          "issueNumber": { "type": "integer" },
          "body": { "type": "string" }
        },
        "required": ["issueNumber", "body"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "posted": { "type": "boolean" }
        },
        "required": ["url", "posted"]
      }
    }
  ]
}

Expected write output:

• src/github.tb with a typed tool PostComment;
• touba.manifest.fragment.json with network and secret_read;
• mcp.bridge.config.json with GITHUB_TOKEN mapped from the handle;
• a *.mcp-bridge.mjs handler that calls tools/call;
• a report listing imported or refused tools.

This output is still a contract. The project must review the diff, grant the secret handle, choose the execution provider and run with traces.

REST and OpenAPI

Most community integrations are HTTP APIs with keys. The Touba pattern is stable:

Structure

types .tb
  describe the request and response
tool .tb
  declares network and expected secrets
manifest
  binds the tool to the handler and secret handles
handler
  calls the REST API and normalizes the response
trace
  records authorization, refusal or success

The REST/OpenAPI scaffold produces these files without granting silent authority:

Terminal

touba rest scaffold rest.search.json \
  --module integrations.web_search \
  --out integrations/web-search \
  --mode plan

--mode write creates the .tb source, manifest fragment, rest.handler.config.json, HTTP handler, secrets template, generation report, and local README. --mode check verifies that generated artifacts remain aligned with the configuration file.

The developer reviews the diff, chooses grants, binds secret handles and validates the run.

REST Example

A keyed search API becomes an explicit Touba tool:

web-search.tb

module integrations.web_search

type WebSearchRequest
    query is Text
    max_results is Int

type WebSearchResult
    summary is Text
    source_count is Int

tool SearchWeb
    takes request as WebSearchRequest
    gives WebSearchResult
    requires network, secret_read
    secrets WEB_SEARCH_API_KEY

The project manifest then binds tool:integrations.web_search/SearchWeb to an HTTP handler and the WEB_SEARCH_API_KEY handle. The expected trace should show binding authorization or refusal without exposing key values or raw payloads.

LangChain And Function Calling

A LangChain tool or OpenAI function-calling schema already carries three useful ideas: a name, a description and an argument schema. Touba keeps those ideas, then separates them:

Existing mental model	Touba separation
model-callable function	tool declared in .tb
argument schema	Touba type and AIR validation
function body	host handler
API key	secret handle outside the agentic payload
model choice	agent uses, callable_by and decision provider
application logs	structured Touba trace

This separation makes the capability easier to review. The model can still choose useful capabilities, while execution authority remains explicit.

LangChain Example

Before

@tool
def search_web(query: str, max_results: int = 5) -> str:
    ...

In Touba, the function body remains in the host handler. The contract becomes reviewable:

After

tool SearchWeb
    takes request as WebSearchRequest
    gives WebSearchResult
    requires network, secret_read
    secrets WEB_SEARCH_API_KEY

The model no longer receives an opaque function. It sees a declared capability, bounded by uses, manifest, grants, budgets and traces.

OpenAI Function Calling Example

A function JSON schema:

function schema

{
  "name": "send_notification",
  "parameters": {
    "type": "object",
    "properties": {
      "channel_ref": { "type": "string" },
      "message": { "type": "string" }
    },
    "required": ["channel_ref", "message"]
  }
}

becomes a Touba type, then a tool that can be composed by a skill with human.approve before the external effect.

Make your integration reusable

After validating the business behavior and refusal paths, distribute it as a Touba package. The package can combine tools, handlers, skills, agents and contextual procedures under one manifest. The Hub lists published packages; it does not imply that an example connection is an available integration.

Minimal Path

1. Choose one existing integration and one external effect.
2. Write or generate the Touba tool and its types.
3. Run touba prepare --mode plan, then touba prepare --mode write.
4. Review the manifest, grants, secrets and payload constraints.
5. Implement the handler or connect the generated MCP bridge.
6. Run with --trace-out and review refusals or success.
7. Promote the integration to a package only when the contract is stable.

This path keeps the intelligence of existing tools while adding the governance, reliability and auditability that prompt-first integrations lack.