TopxAI Models

Ask a model

ask_model

Send a prompt to one text model of the TopxAI catalogue and return its reply. The models reason before they answer and the reasoning counts toward max_output_tokens, so leave at least 4096 tokens for a full answer or pass a lower reasoning_effort. Billed at the model's token price, reasoning included, plus a $0.001 call fee; the reply reports the exact charge.

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": {
      "model": "<model>",
      "prompt": "<prompt>"
    },
    "name": "ask_model"
  }
}

Input Schema

Name	Required	Description
`model`	Yes	Model to ask; list_models shows the choices and prices.
`prompt`	Yes	The user message sent to the model. Include every piece of context the model needs; it sees nothing else.
`system`	No	Optional system prompt.
`temperature`	No	Optional sampling temperature.
`max_cost_usd`	No	Refuse the call, before anything is billed, when its estimated cost (prompt, max_output_tokens and the call fee) exceeds this amount.
`reasoning_effort`	No	Optional thinking effort. Each model takes its own set and list_models shows them with the default, which applies when this is omitted. A lower effort answers sooner and costs less; the reasoning is billed as output and counts toward max_output_tokens.
`max_output_tokens`	No	Upper bound on the reply, reasoning included; the reasoning itself is not returned. Below 4096 a model may stop before writing any text, and that call is still charged.

Output Schema

Name	Required	Description
`error`	No	Present on a failed call: category (client, wallet, topxai, upstream, budget), message, charged, charged_usd.
`model`	No
`route`	No
`usage`	No
`charged`	No	Whether the wallet was debited for this call.
`request_id`	No	The relay request id; the same id appears in the usage log.
`charged_usd`	No	The recorded wallet debit in USD, model price and call fee included.
`call_fee_usd`	No
`finish_reason`	No
`reasoning_effort`	No	The effort the call asked for; the model's default when it named none.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 6, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that reasoning precedes the answer, that reasoning consumes max_output_tokens without being returned, and that a truncated call is still charged. The exact pricing model (token price plus a $0.001 call fee, reported in the reply) is spelled out. It stops short of covering error behavior or rate limits.

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?

Three sentences, front-loaded with purpose and followed by the token-budget caveat and the billing note; nothing is redundant. The middle sentence is dense but still readable and earns its length.

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 seven-parameter generative tool with an output schema, the description covers the main pitfalls: truncation risk, invisible reasoning, cost estimation, and charge reporting. Return values need not be described because an output schema exists, leaving only minor gaps such as failure modes.

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; the description goes beyond it by explaining the interaction between reasoning_effort and max_output_tokens and by recommending at least 4096 tokens. That adds practical meaning an agent would not infer from the schema alone.

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 first sentence gives a concrete verb and resource: send a prompt to one text model and return its reply, with the 'one model' scope made explicit. It does not explicitly distinguish itself from the sibling 'judge' tool, so it falls short of a 5 even though the core purpose is unambiguous.

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

Usage Guidelines3/5

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

Usage is implied by the description's framing (single-model prompting), and it gives useful operational advice about leaving 4096 tokens or lowering reasoning_effort. However, it never states when to pick this over 'judge' or when to consult 'list_models' first, which the schema mentions but the description does not.

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

All TopxAI Models 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.

Resources

Need Help?