Skip to main content
Glama

BotSpot: AI Trading, Backtests and Bots

Fetch position telemetry for a deployment

get_deployment_position_telemetry
Read-only

A saved-code-only edit does not require live orders or positions. Implement confirmed-fill handling in the strategy runtime without inventing a current fill or deployment. The live evidence requirements below apply only when investigating or preserving state for an existing live deployment. Requires the exact deploymentId from a matching list_deployments row or supplied by the user. If discovery returns no matching deployment and the user has not supplied its deploymentId, live telemetry is unavailable: continue an authorized saved-code repair using the saved revision and supported order/fill lifecycle, and disclose the missing live evidence. Do not probe with placeholders, strategy IDs, bot IDs, or invented deployment IDs; this tool cannot discover a deployment from them. Returns position snapshots recorded for a deployment, dated by lastUpdated. These may include imported broker-account positions; a deployment wrapper does not establish ownership or complete account history. This does not refresh broker marks. For a named bot account report, use show_bot_activity first; it includes current linked broker data. Do not preflight or repeat that report with this historical positions reader. Unavailable orders or positions are unknown, not an empty result. Each position includes symbol, quantity, avg_fill_price, current_price, market_value, pnl, and a nested asset object with asset_type (stock/option/crypto/future), strike, expiration, right (CALL/PUT), and multiplier for options. Use this after list_deployments for recorded deployment position details or an explicit correction to deployment position counts (for example 'not just the count'). A current performance question that also mentions holdings still uses show_bot_activity first. list_deployments.live.positions.count alone is not position evidence. Also use this as the live-bot fallback when broker_snapshots(action="list") or broker_snapshots(action="positions") returns no accounts/positions or stale/unavailable snapshot telemetry; empty broker snapshots do not prove running deployments have no positions. For multiple relevant deployments, call this for each deployment whose actual holdings you will report. If you plan to say a deployment has zero positions, call this tool for that deployment first and rely on the explicit empty positions result, not list_deployments.live.positions.count. For an existing live deployment, fill-basis, cost-basis, 'why didn't it sell', latest buy, sell-trigger basis, or latest bot-owned entry questions, positions are not enough by themselves: avg_fill_price can differ from the latest bot-owned filled order. Pair this with get_deployment_order_telemetry and prefer explicit bot-owned filled order evidence when order evidence conflicts with position averages. Orders and positions are separate evidence attempts: a failed get_deployment_order_telemetry call does not satisfy get_deployment_position_telemetry, and list_deployments does not replace either tool for fill-basis evidence. Related order snapshots may include imported broker-account orders. A botId or deploymentId wrapper does not prove that this strategy submitted an order; compare order_id with deployment logs and run timing. Set includeRecentOrders=true when a compact position snapshot plus recent related orders by symbol is useful, but treat relatedRecentOrders as recent supporting evidence, not complete position provenance. Do not base a latest-fill code fix on position.avg_fill_price when bot-owned fill/order evidence is available or supplied by the user. A user-supplied fill is recovery evidence only after order/position tools fail or are unavailable; it is not a reason to skip get_deployment_order_telemetry or get_deployment_position_telemetry. If order/position evidence is unavailable and the user supplied a concrete bot-owned fill, record/use that concrete fill in executable strategy state as the bootstrap latest verified fill until live order evidence replaces it; do not leave a new verified-fill variable unset. If the user says to stop using position.avg_fill_price or says it is stale/wrong, the saved code must remove executable calls such as position.avg_fill_price, getattr(position, 'avg_fill_price'), or average_fill_price(...) instead of keeping them as fallback logic. Do not solve this by trying orders first and then falling back to avg_fill_price; hold/skip, keep the last verified bot-owned fill, or use the concrete bot-owned fill supplied by the user instead. Set history=true to get versioned position snapshots showing how holdings changed over time, with filtering by symbol, time window (ISO-8601 or Unix epoch), sorting, and pagination via nextToken. Use this for recorded deployment positions or their historical changes; current linked-account holdings belong to show_bot_activity.

Input Schema

NameRequiredDescriptionDefault
sortNo
limitNo
symbolNo
historyNo
nextTokenNo
endTimeIsoNo
deploymentIdYes
endTimestampNo
startTimeIsoNo
startTimestampNo
recentOrdersLimitNo
includeRecentOrdersNo
recentOrdersHoursAgoNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description adds substantial behavior: results are historical snapshots (not refreshed broker marks), may include imported broker-account positions, a deployment wrapper does not establish ownership or complete account history, and unavailable data is 'unknown, not an empty result'. It also enumerates the returned fields (symbol, quantity, avg_fill_price, current_price, market_value, pnl, nested asset object) and warns that avg_fill_price can diverge from the latest bot-owned filled order.

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

Conciseness2/5

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

A single enormous block in which roughly half the text is agent policy unrelated to invoking this tool — how to repair saved code, whether to remove position.avg_fill_price references, how to bootstrap a verified fill from a user-supplied value. The genuinely useful parts (what it returns, when to prefer show_bot_activity or order telemetry, parameter behavior) are buried mid-paragraph with no structure, making it hard to front-load the essentials.

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

Completeness4/5

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

For a 13-parameter, no-output-schema, read-only tool, the description is more than complete on the data model: it names every returned position field, explains history mode, and covers the main sibling/fallback relationships. The completeness is undercut by being entangled with unrelated code-editing instructions, which makes it harder to extract the calling contract, but nothing essential to calling it correctly is missing.

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 0% across 13 parameters, so the description has to carry the load. It does explain history=true, filtering by symbol, time window as ISO-8601 or Unix epoch, sorting, pagination via nextToken, and includeRecentOrders with recent related orders as supporting rather than provenance evidence. But limit, recentOrdersLimit, recentOrdersHoursAgo defaults, and the interaction between window filters and history mode remain unexplained, so compensation is only partial.

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

Purpose4/5

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

The description does state a specific verb and resource — 'Returns position snapshots recorded for a deployment, dated by lastUpdated' — and calls itself a 'historical positions reader', which separates it from show_bot_activity (current linked broker data) and get_deployment_order_telemetry (orders). However, the purpose statement is not front-loaded: the first three sentences are about saved-code edits and live-evidence requirements, so an agent must read deep into the text to learn what the tool actually returns.

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

Usage Guidelines5/5

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

Unusually explicit routing: use after list_deployments, use as fallback when broker_snapshots returns empty/stale, use show_bot_activity first for named bot account reports, pair with get_deployment_order_telemetry for fill-basis questions, call once per deployment when reporting multiple holdings. It also states exclusions and anti-patterns ('Do not probe with placeholders, strategy IDs, bot IDs, or invented deployment IDs') and clarifies that list_deployments.live.positions.count is not position evidence.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.