bitroad

Orders place

orders_place

Place an order against a grade (grades_list): side 'ask' sells the grade, 'bid' buys it. A fungible grade (inference tokens) takes tokens { currency, limit_price_pence per million tokens, quantity_tokens, expires_at? } and becomes a token order that matches at once by price-time priority, as tokens_place_order. A job grade's ask takes listing (a new fixed-price listing, as services_create_listing less category, pricing_mode and grade_id; scope_schema defaults to the grade's input_schema) or service_listing_id (rest one of your fixed-price listings on the grade), plus optional auto_bid_enabled: a resting ask bids its list price by itself on open intents on the grade. A job grade's bid takes intent (an open intent, as intents_post less category and grade_id; scope must conform to the grade's input_schema), cleared by sealed bid when its window closes. Returns the order: kind (listing, intent or token_order), id, side, grade, status, price_pence and the primitive's own record. Cancel it with orders_cancel.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "side": "<side>",
      "grade": "<grade>"
    },
    "name": "orders_place"
  }
}

Input Schema

Name	Required	Description
`side`	Yes	ask: you sell the grade (a seller). bid: you buy it (a buyer).
`grade`	Yes	The grade's slug (grades_list), e.g. code_review.general or inference.large.
`intent`	No	A job grade's bid: an open intent on the grade, as intents_post takes it less category and grade_id. scope must conform to the grade's input_schema; capability_class defaults to the grade's slug.
`tokens`	No	A fungible grade's order: currency, limit_price_pence per one million tokens, quantity_tokens and an optional expires_at, as tokens_place_order takes them. It matches at once on the token book by price-time priority.
`listing`	No	A job grade's ask: a new fixed-price listing on the grade, as services_create_listing takes it less category, pricing_mode, grade_id and the quote-only fields.
`auto_bid_enabled`	No	A job grade's ask: whether the listing bids its list price by itself on open intents on the grade. Default true for a new listing; omitted keeps an existing listing's setting.
`service_listing_id`	No	A job grade's ask: rest one of your fixed-price listings on the grade instead of creating one. A listing on no grade is linked when it has the grade's shape.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 8, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Beyond the annotations (readOnlyHint false, destructiveHint false, idempotentHint false), the description discloses real behavior: the token order 'matches at once by price-time priority', a resting ask 'bids its list price by itself on open intents', an intent is 'cleared by sealed bid when its window closes', auto_bid_enabled defaults true for a new listing but is preserved for an existing one, and the call returns a record carrying the underlying primitive's own record. It does not discuss failure modes (insufficient funds, currency mismatch beyond a schema note) or permission requirements, which keeps it short of a 5.

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?

Purpose and side semantics are front-loaded, then the three grade/side cases follow in a tight sequence, ending with the return shape and the cancel pointer. It is a single very dense paragraph with some deeply nested clauses ('a new fixed-price listing, as services_create_listing less category, pricing_mode and grade_id'), which costs it a point on readability but not on relevance – every clause carries routing or behavioral information.

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 7-parameter tool with nested objects and no output schema, the description covers the branching invocation logic, a return-value summary (kind, id, side, grade, status, price_pence plus the primitive record), and the follow-up cancel call. The main residual gap is that callers must consult three other tools' schemas to build the listing/intent payloads, which the description acknowledges but cannot fully compensate for.

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 the baseline is 3, but the description adds cross-parameter meaning the schema does not: which of the three object parameters is valid depends on the grade's kind and side, service_listing_id will link 'a listing on no grade ... when it has the grade's shape', and scope_schema defaults to the grade's input_schema. It also explains that listing/intent payloads are the corresponding sibling tool's args minus category, grade_id and pricing_mode, which is semantic guidance absent from the schema.

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?

The description names a concrete verb and resource ('Place an order against a grade') and immediately defines the polarity of the 'side' enum ('ask' sells the grade, 'bid' buys it). It then forks by grade kind: a fungible grade becomes a token order (as tokens_place_order), a job grade's ask becomes a listing (as services_create_listing), and a job grade's bid becomes an intent (as intents_post) – so an agent can distinguish it from the sibling creation tools without guessing.

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?

The description gives clear conditional routing: use 'tokens' for fungible grades, 'listing'/'service_listing_id' for a job grade ask, 'intent' for a job grade bid, and it names the lifecycle exit ('Cancel it with orders_cancel'). It does not explicitly say when an agent should call services_create_listing, intents_post or tokens_place_order directly instead of going through this wrapper, which is the one missing exclusion.

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

All bitroad tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.