Code Mode - TrueFoundry Docs

Also known as Programmatic Tool Calling (PTC)

What is Code Mode?

Code Mode uses the Sandbox to let the agent write code to chain tool calls with arbitrary logic. The agent is provided with utilties to inspect output schema of tools and a mcp client inside the sandbox to allow listing, inspecting and calling allowed tools programmatically.

Programmatic tool calls — The Agent writes Python in the sandbox to call MCP tools and work with the response in code:

import asyncio
from mcp_client import call_tool

async def main():
    result = await call_tool(
        "github-mcp",
        "list_pull_requests",
        body={"owner": "truefoundry", "repo": "docs-mintlify", "state": "open"},
    )
    for pr in result["pull_requests"]:
        print(pr["number"], pr["title"], pr["user"]["login"])

asyncio.run(main())

Code Mode is enabled by default. The Agent uses it dynamically when the task calls for it.

When does Agent use Code Mode?

Aggregate or format tool output

Use case: The user wants open PRs grouped by contributor with a count for each author.

With Code Mode — The Agent calls the tool inside a script, groups or aggregates in code (for example Counter on author login), and prints only the summary table.
Without Code Mode — The full tool response is added to the conversation. The model must read every PR object and produce counts per author in natural language.
- Context bloat — Dozens of PR records with titles, labels, and metadata fill the context even though the user only asked for counts.
- Hallucination — The model can miscount PRs per author, merge two usernames, or invent a contributor who is not in the response. Group-by and count tasks are especially error-prone when done from prose rather than code.

User

How many open PRs does each contributor have on truefoundry/docs-mintlify?

Assistant

Let me check the output schema for the GitHub list-pull-requests tool, then count PRs per author in one script.

The Agent calls get_tool_output_schema so it knows the shape of the tool response before writing Code Mode scripts. With a defined outputSchema, the model can read and transform fields in code safely instead of guessing keys or types from raw JSON.

get_tool_output_schema

Tool Call

{
  "mcp_server": "github-mcp",
  "tool_name": "list_pull_requests"
}

Tool Response

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "pull_requests": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "number": { "type": "integer" },
            "title": { "type": "string" },
            "user": {
              "type": "object",
              "properties": {
                "login": { "type": "string" }
              },
              "required": ["login"]
            }
          },
          "required": ["number", "title", "user"]
        }
      }
    },
    "required": ["pull_requests"]
  }
}

Assistant

sandbox

Tool Call

cat << 'EOF' > /tmp/prs_by_author.py
import asyncio
from collections import Counter
from mcp_client import call_tool

async def main():
    result = await call_tool(
        "github-mcp",
        "list_pull_requests",
        body={
            "owner": "truefoundry",
            "repo": "docs-mintlify",
            "state": "open"
        }
    )

    prs = result.get("pull_requests", [])
    counts = Counter(pr["user"]["login"] for pr in prs)

    print(f"Open PRs: {len(prs)}\n")
    print(f"{'Author':<24} {'Count':>6}")
    print("-" * 32)
    for login, count in counts.most_common():
        print(f"{login:<24} {count:>6}")

asyncio.run(main())
EOF
python3 /tmp/prs_by_author.py

Tool Response

Open PRs: 7

Author                    Count
--------------------------------
alice-dev                     3
bob-eng                       2
carol-docs                    1
deb-docs                      1

Assistant

On truefoundry/docs-mintlify there are 7 open PRs across 4 contributors: alice-dev (3), bob-eng (2), carol-docs (1), and deb-docs (1).

Chain tool calls

Use case: The user wants to know what metrics are available for app my-app in the tfy-test-cluster:test-ws workspace.

With Code Mode — The Agent runs list_applications and list_app_metric_charts in one script. It finds my-app in the first response, passes the app id and workspaceId into the second call, and prints only the chart table.
Without Code Mode — The Agent calls the first tool, waits for a model turn, then must copy IDs and other fields from the JSON into the second tool call.
- Context bloat — The full list_applications response (pagination, metadata, every app field) sits in the conversation before the second call runs.
- Longer to finish — Each tool hop needs another model call in between, which adds latency.
- Hallucination — The model can typo an applicationId or workspaceId, pick the wrong app from a long list, or drop a required field so the second call fails or returns the wrong charts.

User

What metrics are available for app my-app in the tfy-test-cluster:test-ws workspace?

Assistant

I need schemas for list_applications and list_app_metric_charts, then I will resolve the app and list its charts in one script.

get_tool_output_schema

Tool Call

{
  "mcp_server": "truefoundry-mcp",
  "tool_name": "list_applications"
}

Tool Response

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "data": { "type": "array" },
      "pagination": { "type": "object" }
    },
    "required": ["data", "pagination"]
  }
}

get_tool_output_schema

Tool Call

{
  "mcp_server": "truefoundry-mcp",
  "tool_name": "list_app_metric_charts"
}

Tool Response

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "step": { "type": "string" },
      "graphs": { "type": "array" }
    },
    "required": ["step", "graphs"]
  }
}

Assistant

sandbox

Tool Call

cat << 'EOF' > /tmp/get_metrics.py
import asyncio
from mcp_client import call_tool

async def main():
    apps_result = await call_tool(
        "truefoundry-mcp",
        "list_applications",
        body={
            "applicationName": "my-app",
            "workspaceFqn": "tfy-test-cluster:test-ws"
        }
    )

    apps = apps_result.get("data", [])
    if not apps:
        print("No application found")
        return

    app = apps[0]
    app_id = app["id"]
    workspace_id = app["workspaceId"]
    print(f"Found app: {app['name']} | ID: {app_id} | WorkspaceID: {workspace_id}")

    charts_result = await call_tool(
        "truefoundry-mcp",
        "list_app_metric_charts",
        body={
            "applicationId": app_id,
            "workspaceId": workspace_id,
            "filterEntity": "application"
        }
    )

    graphs = charts_result.get("graphs", [])
    step = charts_result.get("step", "N/A")
    print(f"\nQuery step: {step}")
    print(f"Charts available: {len(graphs)}\n")
    print(f"{'#':<4} {'Chart ID':<50} {'Name':<45} {'Type':<25}")
    print("-" * 130)
    for i, g in enumerate(graphs, 1):
        print(f"{i:<4} {g['chart']:<50} {g['name']:<45} {g['chartType']:<25}")

asyncio.run(main())
EOF
python3 /tmp/get_metrics.py

Tool Response

Found app: my-app | ID: sm3ce3pewjy647a04fsp14z3 | WorkspaceID: cm1j7d9x5002101tu35bvadt8

Query step: 1800s
Charts available: 12

#    Chart ID                                           Name                                          Type
----------------------------------------------------------------------------------------------------------------------------------
  cpuUsage                                           Total CPU Usage                               line
  memoryUsage                                        Memory Usage                                  line
  networkBytes                                       Network Usage                                 line
  requestVolume                                      Request Volume                                stacked_area
  requestDuration                                    Request Duration                              line
  diskThroughput                                     Disk Throughput                               line
  podStatus                                          Pod Status                                    stacked_area
  quantileOverTimeCpuUsage                           Peak and P50 CPU Usage                        line
  cpuThrottling                                      CPU Throttling                                line
 containerRestarts                                  Container Restarts                            bubble
 probeFailures                                      Readiness/Liveness probe failures             bubble
 imagePullTime                                      Image Pull Time                               bubble

Assistant

my-app in tfy-test-cluster:test-ws has 12 metric charts (CPU, memory, network, request volume, and others). Query step is 1800s.

Documentation Index

​What is Code Mode?

​When does Agent use Code Mode?

​Aggregate or format tool output

​Chain tool calls

What is Code Mode?

When does Agent use Code Mode?

Aggregate or format tool output

Chain tool calls