Agent Recipes

Every recipe begins from inspected state, names the exact permissions it needs, and ends with a human-verifiable product result.

Start from the task recipes below — each states its goal, the permissions and controls it relies on, the expected result, and how to recover when a step fails. The advanced section adds a capability graph and six trading playbooks.

Generic discovery-first workflows

These recipes describe objectives and proof gates, not hard-coded call sequences. Discover the current signature and effective policy through tradescript_list_controls, then invoke only returned controls through tradescript_call.

Every recipe starts the same way:

1. Read tradescript://sessions and select one opaque session.
2. Call tradescript_get_context for { "scope": "session" } and inventory available targets.
3. Select an explicit session, chart, or widget target and read its context.
4. List the target's effective controls and record the owning controller revisions.
5. Mutate with current expected revisions and a stable operation identity where retry deduplication matters.
6. Verify with context and bounded events; finish with tradescript_snapshot when the outcome is visible.

Navigate and inspect

Goal: change symbol, interval, and chart type; wait for data; inspect the visible range; then fit the viewport.

Requires: read access with chart navigation controls; no approvals. Expected result: the chart shows the requested symbol, interval, and chart type with a fitted viewport, proven by context and a snapshot. If it fails: a missing control means the capability is not mounted for this target — re-read tradescript_list_controls and pick a supported target instead of retrying.

• Discover chart controls for symbol, interval, chart type, data readiness, visible range, pan, and zoom.
• Route every call to the selected { scope: 'chart', chartId } target.
• Apply one semantic change at a time with the current data or viewport revision required by its descriptor.
• Wait for chart data readiness before reasoning from bars or pixels.
• Verify symbol, interval, chart type, loaded data, and visible range in context.
• Capture the final chart image.

Build a technical-analysis view

Goal: add a moving average and RSI pane, then annotate a support zone derived from visible market facts.

Requires: read plus write access to indicator and drawing controls; no financial permissions. Expected result: the moving average overlays price, RSI occupies its own pane, and the support-zone drawing sits at the stated data coordinates. If it fails: an unknown indicator or tool id means the catalog does not contain it — re-read the catalog resource rather than guessing; a revision conflict means another actor edited content — re-read context before re-applying.

• Read the built-in indicator catalog; do not invent an indicator ID.
• Add indicators, retain returned instance IDs, and update inputs/styles through those IDs.
• Discover the drawing-tool catalog and exact drawing signature.
• Submit time/price points in data coordinates instead of approximate screen clicks.
• Verify indicator instances, pane placement, drawing state, content revisions, events, and rendered output.

Agents can operate built-in and host-registered indicator instances. This workflow does not upload or execute runtime TypeScript source.

Read market microstructure

Goal: inspect a bounded L1/L2/tape window and describe only what the supplied feed proves.

Requires: read access to the data controller and subscription channels; no mutations. Expected result: a bounded, timestamped description of quotes, depth, or tape limited to facts the feed proves. If it fails: missing channels mean the datafeed does not declare the capability — report the gap instead of inferring microstructure.

• Confirm the session data controller exposes the requested quote, depth, session, and time-and-sales operations or channels.
• Record instrument identity, source/update timestamps, sequence or gap facts, currency, units, and declared freshness.
• Start tradescript_subscribe with exact channel IDs returned by context and explicit binding identities.
• Keep polling bounded. If events were dropped or sequence quality is unknown, re-read the current snapshot and report the gap.
• Do not infer venue queue position, aggressor, or lossless tick ordering when the adapter did not provide those facts.

Edit and recover with undo

Goal: restyle and move an existing drawing, group it with another object, lock the group, then demonstrate undo and redo.

Requires: write access to drawing/object controls and undo/redo. Expected result: the drawing is restyled, grouped, and locked, and one undo/redo cycle restores the documented states. If it fails: revision conflicts mean concurrent edits — re-read objects and reconsider; never replay a stale mutation.

• Inventory drawing and object IDs first.
• Read the owning content revision before each dependent edit.
• Change only requested public properties and verify each affected ID.
• Read undo/redo state before invoking either action.
• On a revision conflict, re-read context and objects and reconsider the intent. Never blindly replay a stale mutation.

Review a replay

Goal: choose an available start, enter replay, advance bars, annotate the setup, change speed, play, pause, save state, and exit.

Requires: read and write access to replay controls on the chosen chart target. Expected result: replay enters at the chosen start, advances as commanded, and exits with the annotated setup preserved. If it fails: unavailable history means the datafeed cannot serve the requested start — choose an available range from replay state instead of retrying the same start.

• Confirm effective replay controls on the chosen chart target.
• Read replay state after start, jump, step, speed, play, and pause operations.
• Keep replay/viewport revisions separate from content revisions used by annotations.
• Poll replay and bar channels with a bounded subscription.
• Verify paused/final state and rendered output before exit.

Manage a terminal workspace

Goal: link symbols, assign instruments and intervals to charts, rearrange terminal panels, save a layout, and switch tabs without overwriting unrelated work.

Requires: write access to workspace, layout, tab, and panel controls. Expected result: linked symbols, assigned instruments, rearranged panels, and a layout saved under a new name, verified per target. If it fails: a rejected save name or missing panel control means the host reserves that surface — save under an operator-approved name and leave unrelated tabs untouched.

• Inventory chart and widget target IDs from session context.
• Route chart calls to explicit chart targets and panel calls to the owning widget/terminal target.
• Use symbol-link, workspace, layout, tab, and panel controls only after discovering their exact support.
• Save under a new operator-approved name unless overwrite was explicitly requested.
• Verify linked widgets, each chart, panel geometry, workspace state, revisions, and snapshots.

Paper-trading rehearsal

Goal: prepare the visible ticket or ladder, preview and submit one bounded paper order, then close or flatten and prove final account state.

Requires: an explicit trade grant in paper mode, a mounted host risk authority, and operator confirmation before invocation. Expected result: one bounded paper order previews, submits, and settles, with risk decision, receipts, and final (preferably flat) account state proven. If it fails: a denied risk decision or missing trade control is final for this session — report the refusal with its receipt; never retry around a risk authority.

• Require an explicit paper-trading objective and visible host opt-in.
• Confirm the broker declares paper, the session exposes the exact trade controls, and a host risk authority is mounted.
• Read symbol, account, quote freshness, order, position, cash, equity, and buying-power state.
• Mutate the same ticket or ladder controller visible to the human; do not construct a private MCP-only draft.
• Preview when supported, then invoke the financial control with current revisions and one stable operation ID.
• Prove the risk decision, broker receipt, order, fill, position, cash, equity, and buying-power changes.
• Close, cancel, reverse, or flatten as requested and prove the final expected state, preferably flat for a demo mission.

The trade access class is separate from write. A paper grant never widens to live, and live execution is outside this delivery. The server has no built-in per-call approval prompt, so any required operator confirmation must occur before invocation.

Advanced reference: capability graph and trading playbooks

Use these playbooks to define the data quality, permissions, execution posture, and evidence required for a bounded agent workflow.

TradeScript Agent Recipes

These recipes are objectives for customer-owned agents, not hard-coded method sequences or authorization grants. Before every run, discover the mounted targets with tradescript_get_context and obtain the session-effective control set with tradescript_list_controls. A family named below is useful only when the required controller and exact control are present for the intended target.

MCP is the semantic control and supervision plane. Bounded MCP reads and subscriptions do not constitute a lossless high-rate transport, and none of these recipes claims HFT execution. A separate SDK-native event loop, with measured sequencing, loss, latency, and venue behavior, is a later lane.

Capability graph

Each edge requires both a mounted capability and its quality gate. More embedded data unlocks more workflows; missing or weak data removes an edge rather than being estimated by the agent.

Host-supplied fact	Minimum declared quality	Workflows unlocked
Historical bars	Instrument and interval identity, finite timestamps and values, coverage/gap facts, adjustment basis when relevant	Investor, swing/event, portfolio research
Instrument details, fundamentals, filings, news, and events	Provider provenance plus publication/effective time; point-in-time basis for historical decisions	Investor and event research
Real-time L1 and session state	Source/update time, freshness bound, valid bid/ask, trading-session identity, currency and units	Swing monitoring, day trading, option execution checks
Tick tape with aggressor	Instrument/venue identity, exchange and receipt time, ordering or explicit gap state, unambiguous aggressor	Tape reading, footprint, CVD, supervised scalping
L2 snapshots and deltas	Venue/instrument identity, monotonic sequence, snapshot/delta boundary, gap detection and explicit resynchronization	Liquidity, imbalance, queue-aware research; not HFT through MCP
Options chain, quotes, volatility, and Greeks	quote_timestamp, quote_freshness, per-field availability and provenance, contract multiplier and expiry identity	Options and volatility workflows
Paper broker and account adapter	Broker-declared paper environment, exact operation support, account/currency identity, timestamped orders, fills, positions, cash and buying power	Customer-owned paper execution
Host risk authority and fresh marks	Enforced limits, current utilization, approval state, stale-data policy and immutable decision receipts	Portfolio/risk supervision and bounded paper rehearsal

In compact form:

bars + fundamentals/news --------> investor / long horizon
bars + events + L1 --------------> swing / event
bars + L1 + session + broker ----> day trading
L1 + ordered tape + sequenced L2 -> tape / supervised scalping
option chain + freshness + Greeks -> options / volatility
account + fresh marks + risk ----> portfolio / risk

Shared capability and degradation contract

The family names in these recipes are exact SDK catalog family IDs. The agent still selects exact control IDs from tradescript_list_controls; a family name is never converted into a method name by convention.

• Read-family vocabulary relevant to these playbooks: terminal, chart, chartNavigation, chartLayouts, workspace, marketData, watchlist, watchlists, replay, customization, news, trading, orderFlow, account, options, risk, terminalLayout, and tradingPreview.
• Write-family vocabulary relevant to these playbooks: terminalLayout, chartNavigation, chartSettings, objects, drawings, indicators, chartLayouts, watchlists, orderEntry, orderTicket, marketData, replay, customization, news, symbolLink, depthLadder, accountView, account, optionsView, orderFlow, tradingSession, and tradingLogs; riskPolicy is required only for an explicitly requested host-risk evaluation or policy narrowing.
• Trade-family vocabulary relevant to these playbooks: orders, positions, leverage, and emergency.

Use the following typed degradation rules in every recipe:

1. If a target or controller is not mounted, remove that workflow branch and report the returned agentic.target-not-found or agentic.controller-unavailable result. Do not substitute another target.
2. If an exact control is absent from the effective list, consult the same target's unavailableControls ledger and preserve its SDK-owned reason and detail exactly. If an entry appears in unclassifiedControls, report the control ID and target to TradeScript support; do not invent a reason or attempt the control. Preserve agentic.control-unsupported or agentic.access-denied if an invocation races with a capability/policy change. Never bypass the denial with DOM interaction.
3. Preserve provider failures such as datafeed.unsupported and trading.adapter-unsupported. Do not derive the missing field or simulate a broker operation in MCP.
4. If freshness, provenance, sequence, gap, currency, unit, or adjustment facts do not satisfy the recipe, state the exact missing fact and fall back to the explicitly named lower-capability posture. Unknown quality is not good quality.
5. On revision_conflict, re-read context and ask whether the objective still applies before retrying. Never replay a stale financial intent blindly.

Evidence is always bounded: retain the relevant context revision, compact input window, exact control receipt, resulting controller state, and one snapshot when visual proof matters. Do not dump an unbounded history, tape, depth book, event log, or account ledger.

Investor and long-horizon research

Objective: build a traceable thesis, monitor it, and optionally rehearse an allocation without turning missing fundamentals into model-generated facts.

Required capability facts and quality

• Core research requires resolved instrument identity plus historical bars for the requested horizon. The host must declare coverage, interval, currency, units, gaps, and any split/dividend adjustment basis relevant to the thesis.
• A fundamental or filing thesis additionally requires instrument details or a host custom data surface with provider provenance, publication time, and a point-in-time effective date. Current values must not be used as historical values unless the provider declares that basis.
• A catalyst-aware thesis additionally requires timestamped news or semantic market events. Account-aware sizing requires timestamped balances, positions, cash, buying power, and price marks in compatible currencies.

Exact access families

• Read: marketData, chart, chartNavigation, news, watchlist, watchlists; add account, trading, and tradingPreview only for portfolio-aware sizing, plus risk when an allocation rehearsal must inspect policy, utilization, or decision receipts.
• Write: symbolLink, watchlists, chartNavigation, indicators, drawings, chartLayouts, and terminalLayout for research organization; add orderTicket only to prepare a visible draft.
• Trade: none for research. An optional allocation rehearsal uses orders and positions only after exact controls are separately granted.

Paper-only posture

Default to read/write research. Use the customer's paper adapter for order sizing and rebalancing rehearsal. Live allocation is outside this delivery.

Bounded run and evidence

Read the requested bar window and source facts, annotate the thesis on one chart, build or update one named watchlist, and return the thesis, invalidation conditions, next review time, input timestamps, revisions, and one chart snapshot. If paper execution was requested, include preview, receipt, order/fill state, resulting position, cash, equity, and buying power.

Typed degradation

• Without fundamentals/provenance, downgrade to a price-history thesis and label fundamental conclusions unavailable.
• Without adjustment/coverage facts, describe the raw window but do not compute long-horizon return or drawdown claims.
• Without compatible account currency or fresh marks, stop at a notional proposal. Preserve provider/account unsupported results.

Swing and event-driven workflow

Objective: indicator a bounded catalyst window, define entry/invalidation levels, and optionally rehearse a multi-session order plan.

Required capability facts and quality

• Historical bars must cover pre-event baseline through the requested holding horizon with explicit gaps and adjustment basis.
• Event or news input must carry provider, instrument mapping, publication or effective time, and enough identity to avoid merging unrelated events.
• Quote-aware monitoring requires fresh L1, session status, currency/units, and a clock basis. Overnight plans require the provider and broker to declare the applicable session and order-duration support.

Exact access families

• Read: marketData, news, chart, chartNavigation, replay, watchlist, watchlists, trading, and tradingPreview; add risk for an authorized execution branch that must inspect policy or decision receipts.
• Write: symbolLink, chartNavigation, indicators, drawings, replay, watchlists, orderTicket, and terminalLayout.
• Trade: orders for entry/protective orders and positions for an explicit exit; emergency only when a separately granted emergency control is part of the plan.

Paper-only posture

Use replay or the customer's paper adapter. Live execution is outside this delivery. A chart level is analysis, not a simulated broker-held stop, until paper-broker state proves the order exists.

Bounded run and evidence

Read one event window, mark catalyst/entry/invalidation levels, construct one visible ticket draft, preview it, and report the event provenance, market clock, quote age, chart revisions, preview, and snapshot. If paper execution is authorized, include order, fill, position, and protective-order state.

Typed degradation

• Without a trustworthy event timestamp or instrument mapping, downgrade to a technical swing review and omit event-causality claims.
• Without fresh L1 or session facts, keep the plan unsubmitted.
• Without broker support for the intended duration or protective order, return trading.adapter-unsupported and propose no silent substitute order type.

Day-trading workflow

Objective: monitor current market-data conditions, prepare the exact visible ticket, and optionally perform a bounded intraday paper round trip.

Required capability facts and quality

• Require fresh L1, valid bid/ask, session state, resolved instrument, currency, tick/price format, and the host's freshness bound. Intraday bars must declare interval and gaps.
• Tape or depth may enhance the decision only when their own quality contracts pass. A non-sequenced book must not be described as lossless L2.
• Execution requires broker-declared environment and operation support plus timestamped account, margin/buying-power, order, execution, and position state. Bounded paper automation additionally requires a mounted host risk authority; MCP policy alone is not a risk engine.

Exact access families

• Read: marketData, orderFlow, chart, chartNavigation, trading, tradingPreview, account, risk, and terminalLayout.
• Write: symbolLink, chartNavigation, indicators, drawings, orderFlow, orderTicket, depthLadder, accountView, and terminalLayout.
• Trade: orders and positions; optionally emergency for exact cancel-all or flatten controls. leverage is separate and remains denied unless the objective explicitly requires it.

Paper-only posture

The demonstration posture is paper. Preview first, show side, quantity, type, price, duration, account, estimated costs and protection, then obtain any required operator confirmation. Live execution is outside this delivery. Unknown execution mode is denied.

Bounded run and evidence

Read a bounded bar/quote/tape/depth window, set one chart and ticket objective, preview one order, place no more than the authorized bounded order count, and verify receipt, order, fill, position, cash, equity, buying power, revisions, relevant subscription events, and one snapshot. Close or cancel only through an exact effective financial control.

Typed degradation

• With bars but no fresh L1, downgrade to analysis/replay and do not submit.
• With L1 but no qualified tape/depth, run quote-aware trading without microstructure claims.
• With no mounted risk authority, the workflow degrades to propose/confirm; paper remains available only if the broker declares paper mode.

Tape, order-flow, and supervised scalping

Objective: inspect short-lived liquidity and aggressor behavior and, when authorized, rehearse a tightly bounded paper execution through the shared ladder or ticket controller.

Required capability facts and quality

• Directional tape requires price, size, instrument, exchange/receipt time, and an explicit aggressor. Ordering must be declared; gaps and overflow must be visible.
• Queue, imbalance, and liquidity claims require a venue-scoped L2 snapshot and sequenced deltas, monotonic sequence IDs, gap detection, and explicit resynchronization. L1 or an unsequenced depth image is not queue evidence.
• Execution also requires fresh L1, tick size, session state, broker operation support, account state, and explicit stale-data/disconnect behavior.

Exact access families

• Read: marketData, orderFlow, chart, chartNavigation, trading, tradingPreview, account, and risk.
• Write: orderFlow, depthLadder, orderTicket, chartNavigation, indicators, drawings, symbolLink, and terminalLayout.
• Trade: orders, positions, and optionally emergency. Do not grant leverage as an incidental part of a scalping recipe.

Paper-only posture

Paper is the default. MCP may configure, supervise, inspect, and invoke bounded semantic actions, but its polling/subscription plane is not an HFT event loop. Live execution is outside this delivery. The paper workflow must not be marketed as colocated or lossless high-frequency execution.

Bounded run and evidence

Capture a small sequence-bounded tape/depth window, state the snapshot sequence and gap status, configure the visible tape/heatmap/ladder, preview one order, and—only in authorized paper mode—perform one round trip. Retain first/last sequence, dropped-event evidence, quote age, preview, receipts, fills, position, cash/equity changes, revisions, and one snapshot.

Typed degradation

• Without aggressor, show neutral prints and omit delta/CVD conclusions.
• Without continuous sequence and resynchronization facts, stop queue/imbalance reasoning, mark the window gapped, and downgrade to L1/tape observation.
• On subscription overflow, stale data, disconnect, or gap, stop financial actions and require a fresh snapshot. Do not fill the gap in MCP.

Options and volatility workflow

Objective: compare a bounded option surface, construct a visible strategy draft, and optionally rehearse broker-supported paper execution.

Required capability facts and quality

• Require a canonical option-series snapshot with underlying identity, provider, quote_timestamp, quote_freshness, expiries, strikes, contract codes, type, multiplier, and per-field availability/provenance.
• A volatility/Greeks workflow additionally requires bid/ask, implied volatility and the named Greeks used by the strategy. Each field must be finite, available, fresh enough for the host's bound, and provider-supplied; MCP does not derive missing Greeks.
• Execution requires a mounted option ticket, fresh underlying L1, exact contract identity, broker-supported strategy/order type, duration, account, and preview.

Exact access families

• Read: options, marketData, chart, chartNavigation, trading, tradingPreview, account, and risk.
• Write: optionsView, orderTicket, chartNavigation, indicators, drawings, symbolLink, and terminalLayout.
• Trade: orders for an explicitly supported option order and positions for an explicit close. leverage and emergency are not implied.

Paper-only posture

Default to analysis and the customer's paper adapter. Live option execution is outside this delivery. Never replace a rejected multi-leg paper strategy with independent legs without separate authorization.

Bounded run and evidence

Read one underlying and a bounded expiry/strike window, record freshness and field availability, compare only contracts with the required fields, construct one visible strategy draft, preview it, and capture option-chain/ticket revisions plus a snapshot. For authorized paper execution, also prove broker order, fills by contract, resulting positions, fees, cash, and buying power.

Typed degradation

• Missing Greeks or IV downgrades to price/volume/open-interest comparison; missing fields remain unavailable and are not calculated by MCP.
• Stale option quotes downgrade to historical analysis and block submission.
• Missing strategy support preserves trading.adapter-unsupported; do not split or transform the financial intent in a downstream layer.

Portfolio, exposure, and risk workflow

Objective: explain current exposure, identify limit pressure, and supervise an explicitly authorized rebalance or emergency action.

Required capability facts and quality

• Require account identity/currency, balances, cash, equity, buying power, orders, executions, positions, quantities, cost basis, and timestamped marks. Cross-currency aggregation requires explicit FX marks and timestamps.
• Risk assertions require a mounted host-owned risk authority with enforced limits, current utilization, approval state, stale-data policy, emergency state, and immutable decision receipts. An MCP access grant is not evidence that those risk checks exist.
• Any financial action requires broker-declared execution environment and exact operation support. Cancel-all and flatten must be first-class supported operations, not client loops over single-order controls.

Exact access families

• Read: account, risk, trading, tradingPreview, marketData, options, watchlist, watchlists, and terminalLayout as applicable to held assets.
• Write: accountView, account, orderTicket, optionsView, tradingSession, tradingLogs, watchlists, and terminalLayout; add riskPolicy only for an explicitly requested host-risk evaluation or policy narrowing.
• Trade: positions for explicit rebalance/close, orders for explicit order actions, emergency for exact cancel-all/flatten, and leverage only for a separately requested leverage change.

Paper-only posture

Observe and propose by default. Rehearse allocation/risk changes through the customer's paper adapter. Live portfolio mutation is outside this delivery. Emergency does not mean unrestricted: it is a separately granted exact control family within the simulated environment.

Bounded run and evidence

Read one account or an explicitly bounded account set, normalize only with declared currency/FX facts, report gross/net/notional concentration and current limit utilization, then prepare one proposal. For an authorized mutation, retain preview/risk decision, operation receipt, affected orders/fills/ positions, cash/equity/buying-power deltas, revisions, and a bounded before/after snapshot.

Typed degradation

• Without fresh marks or FX, report raw positions by native currency and omit aggregate exposure/P&L claims.
• Without a mounted risk authority, downgrade from risk-compliant automation to exposure analysis and proposal; do not manufacture limits from prose.
• If atomic cancel-all or flatten is unsupported, report agentic.control-unsupported or trading.adapter-unsupported. Do not emulate the emergency action with a downstream loop.

Supporting chart workflows

Technical-analysis setup

Inspect the active symbol and range, add a moving-average indicator and an RSI pane, draw a support zone from visible price facts, fit the viewport, and verify the final image. Require chart and chartNavigation reads plus indicators, drawings, and chartNavigation writes. If an exact indicator or drawing control is unavailable, omit it and report the typed unsupported result.

Replay review

Read the loaded history, choose an available replay start, enter replay, advance several bars, annotate the observed setup, pause, and report the replay state. Require marketData, chart, and replay reads plus replay and optionally drawings writes. Replay is analysis; it does not authorize trade families.

Workspace cleanup

Inventory drawings, indicators, panes, and comparisons; preserve objects the user names; remove only approved clutter; normalize settings; save a new named layout instead of overwriting an unrelated one. Require the corresponding chart, workspace, and chartLayouts reads and exact objects, drawings, indicators, chartSettings, or chartLayouts writes.

Multi-chart comparison

Inspect the workspace layout and chart IDs, assign requested symbols and intervals explicitly, synchronize only the requested dimensions, and verify each chart's context independently. Require workspace, chart, and chartNavigation reads plus exact chartLayouts, chartNavigation, or symbolLink writes.

Trading rehearsal

Use a broker-declared paper environment only. Preview the order first, show the exact side, quantity, order type, price, duration, and account, obtain explicit operator confirmation in the conversation, submit only when tradescript_list_controls returns the exact trade control for that session and target, then verify broker state and the corresponding chart trading line. The current MCP server does not create a separate per-call approval prompt.

Next steps

• Controls and Resources — the six stable tools every recipe is built from.
• MCP Security and Access — the authority each recipe assumes before it runs.
• Evaluate Agent Control — a bounded evaluation run before you widen access.