Skip to main content
Glama

Read a BrainChain order

brainchain_get_task
Read-only

Read an order's payment, status, grade, result text, and refund transaction, retrying until done. Check next to see what the order state means and what to do.

Instructions

Read an order from brainchain_post_task: the payment, the task's status on BrainChain, Jev's grade, the result text once the work is accepted, and the refund transaction if it is not. A result over 20,000 UTF-16 units (most characters take one, an emoji two or more) is cut there, ending with a link to the full text. Call again after retryAfterSeconds until done is true. next says what the order's state means and what to do. A rejected task stays not done until the refund is sent, when the dispute window closes. Two things end it without a refund transaction: a ruling that pays the model, and a refund the desk gives up sending, when state reads refund-failed and next says who to write to.

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": {
      "order": "<order>"
    },
    "name": "brainchain_get_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
orderYesOrder id returned by brainchain_post_task.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • changedInput schema / properties / order / pattern
      Previous value: -"^0x[0-9a-f]{64}$"New value: +"^0x[0-9a-fA-F]{64}$"
  2. First observedv0.2.0

TDQS

A4.4/5.0
Behavior5/5

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

On top of readOnlyHint/openWorldHint, the description discloses substantive behavior: results are truncated at 20,000 UTF-16 units with a link to the full text, the task is polled via `retryAfterSeconds` until `done`, and a rejected task stays not-done until the refund is sent at dispute-window close. It further explains the two non-refund termination paths, including the `refund-failed` state and who to contact, which is exactly the kind of state-machine context annotations cannot express.

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?

The core action and return contents are front-loaded, and every subsequent sentence carries distinct state-machine information rather than filler. It is dense and relies on backtick field names embedded mid-sentence, which slightly hurts readability, but little is wasted.

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?

There is no output schema, so the description carries the full burden of describing return values, and it does so thoroughly: payment, state, grade, result text with truncation limit, refund transaction, `done`, `retryAfterSeconds`, and `next`. The only parameter is fully covered by the schema, so an agent has everything needed to call and interpret this tool.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema already documents `order` as the id returned by brainchain_post_task along with its 0x pattern. The description only restates that the id comes from brainchain_post_task and adds no format, sourcing, or validation detail beyond it, so the baseline of 3 is appropriate.

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 opens with a specific verb and resource ('Read an order from brainchain_post_task') and then enumerates exactly what is returned: payment, status, Jev's grade, result text, and refund transaction. It explicitly ties the tool to the sibling that creates the order, so an agent can distinguish it from brainchain_get_grade or brainchain_bond_status without opening another schema.

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?

It gives concrete operational guidance: 'Call again after `retryAfterSeconds` until `done` is true', and directs the agent to the `next` field for state interpretation. It also clarifies when a rejected task remains not-done and when it terminates. It does not name an explicit alternative for narrower lookups (e.g., grade-only), so it stops short of full when-not-to-use coverage.

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