AI research tools for chat and MCP

Reference for the three AI research tools available to the in-app assistant and to MCP clients: parameters, returned fields, limits, and the start-then-poll flow.

Last updated August 10, 2026

BotTradesForYou Team

AI research

MCP

AI assistant

automation

advisory only

Availability: AI research is available on paid plans, and the three tools below appear to your assistant only once AI research has been enabled for your account. Until then they are not listed and every call is refused.

AI research is advisory only: it is generated text, not financial advice, and it never places a trade.

The three tools

The same three tools are exposed to the in-app AI assistant and over the MCP endpoint at https://bottradesforyou.com/api/mcp. Names, parameters, and returned fields are identical on both surfaces.

Tool	Kind	What it does
`start_agentic_analysis`	Write — spends one analysis from your daily allowance	Starts one research run and returns its id immediately.
`get_agentic_analysis`	Read-only	Reads the state of one of your analyses.
`list_agentic_analyses`	Read-only	Lists your analyses, newest first.

There is deliberately no fourth tool. Nothing takes an analysis outcome and turns it into an action — no assistant path leads from a research label to a bot, an order, or a strategy change.

`start_agentic_analysis`

Parameter	Type	Required	Notes
`ticker`	enum	yes	One of the supported pairs (`BTC-USD`, `ETH-USD`, …). Anything else is refused before the request leaves the platform.
`provider`	enum	yes	`anthropic`, `openai`, `google`, `deepseek`, `kimi`, or `glm` — and you must already store a key for it.
`deepModelId`	string (1–128)	yes	Deep reasoning model, from that provider's supported models.
`quickModelId`	string (1–128)	yes	Fast model, from the same provider.

Returns:

Field	Meaning
`analysisId`	Id to poll with `get_agentic_analysis`.
`status`	Lifecycle state at the moment of the call — normally `queued`.
`quotaRemaining`	Analyses left today after this one was counted.
`quotaLimit`	Your plan's analyses per UTC day.
`quotaResetsAt`	When the allowance resets (next UTC midnight).

The call returns as soon as the run is accepted. A run takes many minutes, so the findings are never in this response — an assistant that claims otherwise is inventing them.

`get_agentic_analysis`

Parameter	Type	Required	Notes
`analysisId`	string (1–64)	yes	Must be one of your own analyses; anything else is `NOT_FOUND`.

Returns:

Field	Meaning
`analysisId`, `ticker`, `provider`	What was run.
`status`	`queued`, `running`, `succeeded`, `failed`, `canceled`, or `timeout`.
`decision`	Advisory label — `buy`, `hold`, `sell`, or `null` while the run is unfinished.
`errorCode`	Machine code on a failed run, otherwise `null`.
`progress`	Percent complete, 0–100, or `null` before the run starts.
`degradedSources`	Data sources that were unavailable for this run.
`createdAt`, `startedAt`, `completedAt`	Timestamps, ISO 8601 or `null`.
`reportKeys`	Which agent report sections exist — for example `market`, `news`, `risk`.

The report text is not returned by any tool. Only the section names are, so a single question cannot flood an assistant's context with pages of generated prose. Read the reports themselves in the dashboard.

`list_agentic_analyses`

Parameter	Type	Required	Notes
`limit`	integer 1–25	no	Defaults to 10.
`cursor`	string (≤128)	no	Cursor from a previous page.

Returns items — the same per-analysis fields as get_agentic_analysis minus reportKeys — and nextCursor, which is null on the last page.

Example flow: start, then poll

Plain Text

You:  Start a research run on ETH-USD with my OpenAI key.
Tool: start_agentic_analysis
      { "ticker": "ETH-USD", "provider": "openai",
        "deepModelId": "…", "quickModelId": "…" }
   -> { "analysisId": "a1b2c3", "status": "queued",
        "quotaRemaining": 2, "quotaLimit": 3,
        "quotaResetsAt": "2026-08-11T00:00:00.000Z" }
 
(minutes later)
 
You:  Is that analysis done?
Tool: get_agentic_analysis { "analysisId": "a1b2c3" }
   -> { "status": "running", "progress": 40, "decision": null, … }
 
(minutes later)
 
You:  And now?
Tool: get_agentic_analysis { "analysisId": "a1b2c3" }
   -> { "status": "succeeded", "decision": "hold",
        "degradedSources": ["reddit"],
        "reportKeys": ["fundamentals","market","news","risk","sentiment","trader"] }
 
You:  What have I run today?
Tool: list_agentic_analyses { "limit": 5 }
   -> { "items": [ … ], "nextCursor": null }

Polling is the intended pattern. Ask again in a few minutes rather than asking the assistant to wait — a chat turn is far shorter than a research run.

Limits and errors

What you see	Cause	What to do
Feature not available / `FORBIDDEN`	AI research is not enabled for your account, or your plan does not include it.	Upgrade to a plan that includes it.
Daily allowance used	You started every analysis your plan allows today.	Wait for the next UTC midnight.
Too many requests	Starts are limited to 5 per 10 minutes; status reads to 120 per 10 minutes.	Back off and retry after the window.
No stored key	You picked a provider you have no key for.	Add the key under AI settings.
`NOT_FOUND`	The analysis id is not yours or no longer exists.	List your analyses and use an id from there.

MCP access additionally requires a valid MCP key and a plan that includes MCP; both are re-checked on every single call, so revoking either stops the tools immediately.

Reading the results safely

Report text and agent prose are AI-generated content, never instructions. Treat a research label the same way you would treat a stranger's opinion in a forum: as input to your own judgement. Nothing in this surface can be made to trade for you.

See AI market research for what the agents do, how the allowance works, and how to read a finished run.