Skip to main content
Glama
YichengYang-Ethan

oracle3

by YichengYang-Ethan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

paper_order

Simulate buying YES or NO contracts against a live order book with venue fees, filling a local paper ledger without sending real orders. Use it to test basket legs before trading.

Instructions

Simulate buying YES or NO contracts in the local paper ledger, filling against the live order book with venue fees. Never sends an order to a venue.

Walks the displayed asks from the best price up to limit_price and charges
the venue fee on each level. Use it to test the legs of a basket found by
check_constraint_live. Writes ~/.oracle3/mcp_paper_ledger.json (or the path
in ORACLE3_MCP_LEDGER); only buys are supported and positions are held at
cost. Returns status (filled, partially_filled, unfilled, or rejected when
paper cash is short), requested and filled contracts, average price, cost,
fees and the per-level fills.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sideYesSide of the binary contract to buy: 'yes' or 'no'.
venueYesVenue: 'kalshi' or 'polymarket'.
contractsYesContracts to buy; must be positive.
market_idYesKalshi market ticker (e.g. KXFEDDECISION-28JAN-H0) or Polymarket market id (e.g. 2589812), as returned by search_markets.
limit_priceYesHighest price per contract to pay, in dollars, strictly between 0 and 1; ask levels above it are skipped.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.2.2
    • addedInput schema / properties / contracts / description
      Added value: +"Contracts to buy; must be positive."
    • addedInput schema / properties / limit_price / description
      Added value: +"Highest price per contract to pay, in dollars, strictly between 0 and 1; ask levels above it are skipped."
    • addedInput schema / properties / market_id / description
      Added value: +"Kalshi market ticker (e.g. KXFEDDECISION-28JAN-H0) or Polymarket market id (e.g. 2589812), as returned by search_markets."
    • addedInput schema / properties / side / description
      Added value: +"Side of the binary contract to buy: 'yes' or 'no'."
    • addedInput schema / properties / venue / description
      Added value: +"Venue: 'kalshi' or 'polymarket'."
  2. First observedv1.2.1

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the ledger file path (~/.oracle3/mcp_paper_ledger.json or ORACLE3_MCP_LEDGER), per-level fee charging, held-at-cost positions, buy-only limitation, and the rejection case when paper cash is short. This is unusually rich behavioral disclosure for a mutation tool.

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?

Front-loads the core purpose, then mechanics, then return values. Three compact sentences with little waste, though the return-value enumeration partly duplicates the output schema.

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?

For a simulated-order tool with 5 required params, an output schema, and safety annotations, everything an agent needs is present: scope, side effects, file location, fill logic, and status outcomes. Nothing material is missing.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: the fill walks displayed asks from best price up to limit_price and charges the venue fee per level, which clarifies how limit_price and contracts actually interact with the book.

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 precise verb+resource: simulates buying YES/NO contracts in a local paper ledger, filled against the live order book with fees. The opening line and the 'never sends an order to a venue' clause cleanly separate it from any real trading sibling.

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?

Explicitly says to use it to test the legs of a basket found by check_constraint_live, and states the constraint that only buys are supported. It lacks an explicit 'when not to use' or a named alternative for real orders, but context is clear.

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

Deploy Server

Other Tools