# Tools (/docs/mcp/tools)

The three Orakle MCP tools — get_pricing, submit_pricing_job, get_job_result.



Three tools wrap the [REST API](/docs/api) job system; read access is
per-user. `geography` accepts `US`, `GB`, `CA`, `AU`, `AE`; default `US`.

<Callout type="info" title="Sync vs async">
  `get_pricing` blocks. `submit_pricing_job` + `get_job_result` are the async
  pair. Failures return as `isError: true` tool results, not JSON-RPC errors.
</Callout>

## get\_pricing [#get_pricing]

Submits a job and waits. Not read-only; open-world.

**Input**

<TypeTable
  type="{
  query: {
    type: &#x22;string&#x22;,
    description: &#x22;e.g. 'iPhone 15 Pro 128GB Grade B unlocked US'.&#x22;,
    required: true,
  },
  geography: {
    type: &#x22;string&#x22;,
    description: &#x22;ISO 3166-1 alpha-2.&#x22;,
    default: &#x22;US&#x22;,
  },
}"
/>

**Output** — pricing envelope:

```ts
{
  status: string;
  job_id?: string;
  result?: Record<string, unknown>;
  error?: string;
}
```

**Example**

```json
// call
{ "name": "get_pricing", "arguments": {
  "query": "iPhone 15 Pro 128GB Grade B unlocked", "geography": "US" } }

// result (structuredContent)
{
  "status": "completed",
  "job_id": "job_01Hh...",
  "result": { "fused_distribution": { "quantiles": { "p50": 612.0 } } }
}
```

## submit\_pricing\_job [#submit_pricing_job]

Async submit. Returns a `job_id` to poll via `get_job_result`. Not read-only;
open-world.

**Input**

<TypeTable
  type="{
  query: {
    type: &#x22;string&#x22;,
    description: &#x22;Natural-language pricing query.&#x22;,
    required: true,
  },
  geography: {
    type: &#x22;string&#x22;,
    description: &#x22;ISO 3166-1 alpha-2.&#x22;,
    default: &#x22;US&#x22;,
  },
}"
/>

**Output**

```ts
{ job_id: string }
```

**Example**

```json
// call
{ "name": "submit_pricing_job", "arguments": {
  "query": "Galaxy S24 256GB Grade A unlocked", "geography": "GB" } }

// result (structuredContent)
{ "job_id": "job_01HJ..." }
```

## get\_job\_result [#get_job_result]

Status and result of a submitted job. Read-only.

**Input**

<TypeTable
  type="{
  job_id: {
    type: &#x22;string&#x22;,
    description: &#x22;From submit_pricing_job.&#x22;,
    required: true,
  },
}"
/>

**Output** — same envelope as `get_pricing`:

```ts
{
  status: string;
  job_id?: string;
  result?: Record<string, unknown>;
  error?: string;
}
```

**Example**

```json
// call
{ "name": "get_job_result", "arguments": { "job_id": "job_01HJ..." } }

// result while running (structuredContent)
{ "status": "processing", "job_id": "job_01HJ..." }

// result once terminal
{
  "status": "completed",
  "job_id": "job_01HJ...",
  "result": { "fused_distribution": { "quantiles": { "p50": 498.0 } } }
}
```

<Callout type="warn" title="Errors are tool results">
  Failures return `isError: true`, not JSON-RPC errors. Check `isError` (or a
  non-`completed` `status` with an `error` field) before trusting `result`.
</Callout>