tradefloor

Overview Schema Source Related Servers Discussions Admin

Advance a market session

session_step

Advance an open trading session by steps or days, optionally submit agent orders at the first step, and return fills, portfolios, prices, and changes.

Instructions

Advance an open session by a number of steps or days, optionally sending orders for one of its agents at the first step, and get back the fills, each agent's portfolio, the prices and what changed. This is the one session tool that trades. An order is a signed share count (positive buys), {"quantity": q, "limit_price": p} for a limit order, or "cancel"; a malformed order is refused before anything runs, and one the market refuses (the leverage cap, a book that cannot fill) is listed and the rest trade. At most 360 steps a call and 504 days a session; a step costs about a sixth of a day of evaluate_strategies for one entrant. Keeps a checkpoint at the step it ends on. Deterministic: the same calls from the same open give the same result.

Input Schema

TableJSON Schema

Name	Required	Description
`days`	No	Advance through this many market closes, the day in progress counting as the first. Give steps or days, not both.
`agent`	No	The agent the orders are for, one opened with null. May be omitted when the session has exactly one such agent.
`steps`	No	Decision points to advance, 1 or more. Give steps or days, not both; with neither, one step.
`orders`	No	Orders sent at the first step this call runs, keyed by ticker: a signed share count for a market order (positive buys), {"quantity": q, "limit_price": p} for a limit order that waits in the book, or "cancel" to withdraw the agent's waiting orders on that ticker.
`session_id`	Yes	A session id exactly as open_session or session_fork returned it.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.10.1Oct 7, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare a non-idempotent, non-read-only, non-destructive mutation, and the description goes well beyond them: malformed orders are refused before execution, market-refused orders are listed while the rest trade, hard caps of 360 steps and 504 days, a cost analogy to evaluate_strategies, checkpoint retention at the ending step, and deterministic replay. This is exactly the operational context an agent needs before a mutating call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the core action and its order-sending option come first, followed by limits, cost, and determinism guarantees. Every clause carries information, though the paragraph format makes it a fairly heavy read for a single-sentence-style spec.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description needn't itemize return fields, and it still names the key outputs (fills, portfolios, prices, changes). Combined with caps, error handling, and determinism disclosure, nothing material is missing for a 5-parameter mutating tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents session_id, steps, days, agent, and orders. The description restates the order encoding (signed count, limit object, 'cancel') largely in parallel with the schema rather than adding new per-parameter meaning. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Advance an open session by a number of steps or days'), plus the optional order-sending behavior and the return payload. It explicitly positions itself against siblings with 'This is the one session tool that trades,' so an agent can distinguish it from session_state, session_rewind, or close_session without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear triggering context: orders are sent for one agent 'at the first step,' steps or days are mutually exclusive, and it is the only session tool that trades. It stops short of explicitly routing the agent to alternatives (e.g. use session_state to inspect without advancing), so it is strong but not fully explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.