Code mode guide for AI agents

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384---
name: code-mode-reads
description: Decide when to use read-only code mode (the stackyapper_run_code tool) and write scripts that discover tools first, page within the limits, return small summaries, and report failed or incomplete sources. Use for questions that need several reads, paging, or results from more than one app.
---
# Read-only code mode

Code mode runs a short JavaScript script that calls read tools and returns one
result. It is a beta for enrolled workspaces. If the run-code tool is not in your
tool list, use the normal tools. If the user says their workspace was just
enrolled, ask them to refresh or reconnect the AI client.

## Choose the right tool

- One lookup, such as one ticket, user, or device: call the read tool directly.
- Several reads, paging, counting, grouping, or comparing apps: use code mode.
- Creating, changing, or deleting anything, or a read that asks for
  confirmation: use the normal tools. Scripts are read-only and cannot confirm.

## Discover before you call

1. Find tools by describing the whole task with the search tool. To save script
   calls, search and read schemas with the normal tools first, then write the
   script with the exact names. Inside a script, use `tools.search({ query })`.
2. Read exact arguments with the schema tool or `tools.schemas({ tool_names })`.
   Never guess a tool name or argument.
3. If an app has more than one connection, list them with
   `tools.connections({ service })` and pass `connection_id`.
4. Before multi-step work in an app, list and read that app's skills. Skills are
   guidance only and never grant access.

Access is checked again on every call. A tool that worked earlier can be
unavailable now, so handle `tool_unavailable` in every run.

## Write the script

- Write the body of an async function. `await` every `tools` call and end with
  `return`. You can await independent calls with `Promise.all`; at most two
  calls run at once and share the run limits. Fetch dependent pages sequentially.
- Every call returns `{ ok: true, data }` or
  `{ ok: false, error: { code, message, retryable } }`. Branch on `ok`. A failed
  source is unavailable, not empty and not zero.
- Page with the continuation the schema names, such as `next_page_token`,
  `next_cursor`, or a page number. Decide a page cap before the loop. If you stop
  before the last page, return `complete: false` and the number of pages read.
- Ask for only the fields and page sizes you need.
- Return counts, groups, and a few record IDs, not raw records.
- Match records across apps only on a shared identifier. Similar names do not
  prove two records are the same company, person, or device.
- A `read_limit` error means Stackyapper withheld that result because the run
  would exceed its 1 MiB read limit. Return what you have and mark it incomplete.
- A `tool_call_busy` error means earlier requests still occupy both slots,
  including timed-out requests that have not settled. Report the unavailable
  source and return what you have.

## Limits per run

- 12 tool calls, including search, schema, and connection calls
- At most two independent tool calls at once
- 20 seconds per tool call and 30 seconds per run
- 1 MiB of tool results read
- 64 KiB returned; larger results are truncated
- 16 KiB of script
- 500 runs per workspace per UTC day, and two runs at a time

Scripts have no network access, files, packages, timers, storage, or
credentials, and they cannot write to any app.

## Report what happened

- Say which apps and connections you checked, which failed, and their error
  codes.
- Say whether each number is complete. Never describe a capped or partial result
  as the full total.
- If the result was truncated, say so and run again with a smaller summary. Do
  not present the preview as complete.
- If a run stops, read the reason before running again. Calls that finished
  before the stop already happened, and every run counts toward the daily limit.

## Dashboards and saved artifacts

A successful run returns `artifact_handoff`, with suggested tool bindings and
schema signatures for building a dashboard. It holds no app data, is not saved,
and is not a live data source. To save a dashboard, follow the artifact
authoring skill: declare the bindings, validate the artifact, then save it.