cto-tools

name: cto-tools description: Dynamic MCP tool discovery and invocation through generated SDK wrappers first, with cto-tools CLI fallback. agents: [morgan, rex, grizz, nova, viper, blaze, tap, spark, cleo, cipher, tess, stitch, atlas, bolt, block, vex, angie, glitch, lex, hype, tally, chase] triggers: [tool, mcp, escalate, discover tools, capability, search tools]

CTO Tools — Dynamic MCP Tool Access

You have access to MCP tools through the CodeRun CTO tools integration. Use this route order:

1. Generated SDK catalog/wrappers
2. cto-tools CLI fallback
3. Native MCP / raw JSON-RPC (diagnostic/last-resort only)

Integration tiers

1. Source-green — source artifacts and setup partial wired in the repository.
2. Live-reachable — running pod can reach the CTO tools service and generate/list the catalog.
3. CRD-wired — CodeRun controller provides task files and template variables consistently.
4. Agent-adopted — agents follow the route order above and write /workspace/cto-tools-proof.json.
5. Live-enforcement-active — gateway enforces policy against normalized agent identity (CTO_AGENT_ID, CTO_AGENT_SHORT_NAME).

Agent identity

• CTO_AGENT_ID — exact GitHub App name (e.g. 5DLabs-Blaze).
• CTO_AGENT_SHORT_NAME — legacy lowercase short name (e.g. blaze).

These values appear in /workspace/cto-tools-setup.json and are used by gateway policy in tier 5.

Setup JSON (written at startup)

/workspace/cto-tools-setup.json is written during startup with this shape:

{
  "mode": "sdk|cli",
  "agent_id": "5DLabs-Blaze",
  "agent_short_name": "blaze",
  "deno_available": true,
  "cli_available": true,
  "sdk_dir": "/.cto-tools",
  "sdk_files_copied": 3,
  "codegen_ok": true,
  "catalog_path": "/.cto-tools/CATALOG.md",
  "catalog_json_path": "/.cto-tools/catalog.json",
  "codegen_servers": 0,
  "codegen_tools": 0,
  "errors": []
}

Required tool-use proof

For every run where you use CTO tools, write /workspace/cto-tools-proof.json with the actual route(s) used and any fallback(s). Do not claim tool proof without a real call.

primary_route, each calls[].route, and fallback from/to values must be exactly one of: sdk, cli, native_mcp, raw_json_rpc.

Minimum shape:

{
  "used": true,
  "primary_route": "sdk|cli|native_mcp|raw_json_rpc",
  "calls": [
    { "tool": "github_search_code", "route": "sdk", "ok": true }
  ],
  "fallbacks": [
    { "from": "sdk", "to": "cli", "reason": "CTO_TOOL_CATALOG missing" }
  ]
}

If CTO tools were required but unavailable, still write the proof file with used: false, the attempted route, and the error.

Route order (operational detail)

1. Generated SDK catalog/wrappers: use when CTO_TOOL_CATALOG exists and points to a readable catalog. Read the catalog, import generated wrappers from CTO_TOOLS_SDK_DIR (default /.cto-tools), and run with Deno/cto-tools exec.
2. cto-tools CLI fallback: use cto-tools mcp list|describe|call|escalate when generated SDK artifacts are not present or a wrapper call fails.
3. Native MCP / raw JSON-RPC (diagnostic/last-resort only): use only to validate parity, diagnose integration failures, or recover when both SDK and CLI paths are unavailable.

Discover tools via generated catalog

if [ -n "${CTO_TOOL_CATALOG:-}" ] && [ -r "$CTO_TOOL_CATALOG" ]; then
  sed -n '1,160p' "$CTO_TOOL_CATALOG"
else
  cto-tools mcp list
fi

Machine-readable catalog, when generated:

cat "${CTO_TOOL_CATALOG_JSON:-${CTO_TOOLS_SDK_DIR:-/.cto-tools}/catalog.json}"

The catalog includes tool names, descriptions, input schemas, and generated import paths under ${CTO_TOOLS_SDK_DIR:-/.cto-tools}/servers/.

Invoke through generated wrappers

For multi-step workflows or when the SDK catalog is present, write a short TypeScript script and import generated wrappers:

// /tmp/cto-tool-call.ts
import { search_code } from "/.cto-tools/servers/github/search_code.ts";

const result = await search_code({
  q: "authentication middleware",
  repo: "5DLabsInc/cto"
});

console.log(JSON.stringify({ total: result.total_count, items: result.items?.slice?.(0, 3) }, null, 2));

Run it with the SDK permissions available in the pod:

deno run --allow-net --allow-read --allow-write --allow-env --allow-run /tmp/cto-tool-call.ts

For simple single-call workflows, cto-tools exec /tmp/cto-tool-call.ts is also acceptable if available.

CLI fallback

Use the CLI when CTO_TOOL_CATALOG is absent, generated wrappers are incomplete, Deno is unavailable in non-SDK mode, or you need a quick single call:

cto-tools mcp list
cto-tools mcp describe <tool_name>
cto-tools mcp call <tool_name> --json '{"param": "value"}'

Request access to a tool outside your prewarm set:

cto-tools mcp escalate <tool_name> --reason "Need to query deployment metrics for this incident"

Native MCP / raw JSON-RPC (diagnostic/last-resort only)

Only use native MCP tool calls or raw JSON-RPC when:

• SDK catalog/wrappers and CLI are unavailable or failing;
• you are explicitly validating parity between SDK/CLI and the underlying MCP service;
• you need diagnostic evidence for an integration bug.

Record this in /workspace/cto-tools-proof.json as a fallback route with the reason.

Proof update example

Use only the proof-route enum values sdk, cli, native_mcp, or raw_json_rpc for primary_route, calls[].route, and fallback from/to.

python3 - <<'PY'
import json, os
path = "/workspace/cto-tools-proof.json"
proof = {
  "used": True,
  "primary_route": "sdk" if os.environ.get("CTO_TOOL_CATALOG") else "cli",  # sdk|cli|native_mcp|raw_json_rpc
  "calls": [
    {"tool": "github_search_code", "route": "sdk", "ok": True}
  ],
  "fallbacks": []
}
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w") as f:
    json.dump(proof, f, indent=2)
    f.write("\n")
PY

When to use what

• Catalog/discovery: generated CTO_TOOL_CATALOG first; cto-tools mcp list second.
• Single tool call: generated wrapper if catalog is present; otherwise cto-tools mcp call.
• Multi-step workflow: TypeScript script using generated wrappers.
• Access denied: cto-tools mcp escalate with a specific reason, then retry the SDK/CLI route after access is granted.
• Diagnostics/control: Native MCP / raw JSON-RPC only after SDK/CLI attempts or when explicitly requested.