CoinRithm/coinrithm-agent-trading

Official

Overview Schema Source Related Servers Discussions Admin

Report a non-opened PM opportunity

report_pm_opportunity

Record prediction-market evaluations when no position is opened, preserving decision evidence without moving funds. Supports abstained, forecast-only, and expired-quote outcomes for audit and replay.

Instructions

Save a durable SELF-REPORT of a prediction-market evaluation for a decision that did not open a position. This WRITES an evidence record but never moves paper funds; authorization requires the read scope. It does not independently verify your evaluation. Choose abstained, forecast_only (requires your own forecastProbability, 1-99), or quote_expired. Report once per decision cycle; cohort.universeSize records its breadth. Supply a non-empty decisionId and reuse it with the same API key on retries: the first stored record wins. agentTrace.decisionId is a fallback; omitting both creates separate records. Success returns body.decisionUuid and, on replay, body.idempotentReplay=true. Check ok/httpStatus before treating delivery as confirmed; a network error does not prove rejection. Use open_pm_position to place a paper trade.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	Yes	abstained = evaluated but did not bet; forecast_only = formed your own probability without trading (forecastProbability required); quote_expired = a validated open the server rejected at act time.
`slug`	No	Optional subject event slug.
`runId`	No	Your own run id for grouping.
`cohort`	No	Opportunity-cohort breadth (frozen into the artifact).
`source`	No	Optional subject market source slug (e.g. kalshi).
`agentTrace`	No	Optional private trace metadata stored in the caller's ledger.
`decisionId`	No	Non-empty id for this decision, unique within your API key. Reuse for retries. Falls back to agentTrace.decisionId; omitting both creates a new record on each call.
`provenance`	No	Optional self-reported provenance (WHAT RAN). No trust: the server stamps policy versions + providerVerified itself. Any block (even {}) makes the artifact schemaVersion 2.
`reasonCode`	No	Short structured reason (e.g. 'no_edge', 'stale_data').
`marketProbability`	No	The market price (0-100) you observed at the time.
`forecastProbability`	No	Your OWN forecast probability (1-99). REQUIRED for forecast_only; optional for other kinds. Never echo the market price.
`outcomeExternalMarketId`	No	Optional case-sensitive outcome/market id of the subject.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	True when CoinRithm returned a successful 2xx response.
`body`	No	Parsed CoinRithm response body, or raw text when the response is not JSON.
`httpStatus`	Yes	HTTP status returned by CoinRithm, or 0 for network errors.
`ledgerStatus`	No	Ledger write status header returned by CoinRithm, when present.
`ledgerEventId`	No	Private AgentActionEvent id returned by /api/agent/*, when present.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.19Sep 15, 2026

changedInput schema / properties / decisionId / description

Previous value: -"Your own id for this decision — idempotency key within your API key."New value: +"Non-empty id for this decision, unique within your API key. Reuse for retries. Falls back to agentTrace.decisionId; omitting both creates a new record on each call."

changedInput schema / properties / forecastProbability / description

Previous value: -"Your OWN probability (1-99) the chosen side wins. REQUIRED for forecast_only; omit for the other kinds. Never echo the market price."New value: +"Your OWN forecast probability (1-99). REQUIRED for forecast_only; optional for other kinds. Never echo the market price."

Addedv0.1.13Jul 15, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the annotations, the description reveals that this WRITES an evidence record but never moves funds, requires only read scope, does not independently verify the evaluation, honors the first stored record on replay, and has a fallback decisionId path that can create separate records. It also refines the coarse idempotentHint=false by conditioning idempotency on reuse of decisionId, which is not a contradiction.

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

Conciseness5/5

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

The description is dense but every sentence earns its place, covering side effects, authorization, verification limits, idempotency, response fields, error interpretation, and routing to the sibling tool. The safety-relevant non-movement of funds is stated upfront.

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 complex tool with 12 parameters, nested objects, and an output schema, the description includes all key operational context: write behavior, auth scope, idempotency rules, response shape, retry semantics, and how to interpret network errors. Nothing an agent needs to correctly use or safely call this tool is missing.

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

Parameters5/5

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

Although the schema already documents all parameters, the description adds decision-relevant semantics: forecastProbability is required for forecast_only, reusing decisionId guarantees first-record-wins, omitting both decisionId and agentTrace.decisionId creates separate records, and cohort.universeSize records decision breadth. These are exactly the details an agent needs to call the tool correctly.

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 specific action ('Save a durable SELF-REPORT'), a precise resource ('prediction-market evaluation for a decision that did not open a position'), and explicitly contrasts with open_pm_position. It makes clear this is a recording tool, not a trading tool, so an agent can distinguish it from siblings without inspecting schemas.

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?

It provides concrete when-to-use guidance: report once per decision cycle, choose among abstained/forecast_only/quote_expired, supply a decisionId for retries, and use open_pm_position when a paper trade is intended. The description even tells the agent what to check (ok/httpStatus) before treating delivery as confirmed.

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