# Benchmark MCP contract

Read current `list_operations` descriptions before using an operation.
Live schemas control inputs and supported formats.
Examples below show input shapes, not permission to spend credits.

## Tools and output

The public tools are `whoami`, `list_operations`, `query`, and `mutate`.
`whoami` reports the workspace and `mutationsEnabled`.
`list_operations.operation` returns one operation's inputs, result, and errors.
Its `filter` searches operation names and descriptions, not posts or creators.

The `query` and `mutate` envelopes require `operation` and `input`.
Set `format: "markdown"` for readable results or `format: "json"` for calculation.
The default is JSON.
Optional `fields` selects top-level response data fields. It does not reduce the documented charge.

| Operation | Tool | Cost and use |
| --- | --- | --- |
| `readPostsEnriched` | `query` | Paid stored analysis for a known public post. |
| `readLinksEnriched` | `query` | Paid stored analysis for a known public link. |
| `readProfileHistory` | `query` | Paid stored page of Basic posts. Each cursor page is a new request. |
| `refreshProfileHistory` | `mutate` | Paid bounded acquisition for a known account. |
| `refreshPostsEnriched` | `mutate` | Paid enrichment for a known public post. |
| `getDataRequestStatus` | `query` | Free polling without result delivery. |
| `getDataRequestResult` | `mutate` | Free result delivery, once only. |
| `getCollection` | `query` | Free legacy status/result route. Can consume delivery. |

`mutate` requires a write-enabled session and approved mutation scope.
Missing access does not authorize a billing or scope change.

## Bound and track charges

Use [current pricing and credits](https://docs.benchmark.app/pricing-and-credits/) before a new paid operation type.
Operation discovery does not provide a price estimate.
Calculate a bound for the selected requests, including cursor pages and enriched examples.
For example, three stored-history pages cost `3 × the current per-page price`.
Count a shorter or empty valid page at its documented request price.
A repeated successful stored read is a new paid request, not free formatting.

A reservation is not a final-charge ceiling.
Enriched completion can exceed its reservation, and there is no per-request `maxCredits` input.
If available inputs and pricing cannot bound a final charge within the approved cap, stop before that request.
Explain the uncertain cost and offer available evidence or a scope whose cost can be bounded.
Do not start parallel paid requests.

Track `operationId`, `tariffVersion`, `status`, `reservedCredits`, and `chargedCredits` from receipts.
Count each operation once: pending reservations reduce the remaining cap. Final charges replace those reservations.
Remove duplicate canonical URLs and reuse cached results.
Stop at the cap, uncertain billing, access errors, or terminal failures.
After an uncertain response, check the known job status before another paid request.

## Request and deliver

For a known post, request its current operation description:

```json
{"operation":"readPostsEnriched"}
```

After scope and budget approval, a `query` uses this shape with the selected original URL:

```json
{"operation":"readPostsEnriched","format":"markdown","input":{"target":{"reference":"https://www.youtube.com/watch?v=oblaHqULUHk"}}}
```

For `refreshProfileHistory`, set explicit `maxPosts` and `maxPostAgeDays` within the current schema.
Do not rely on defaults to define scope.
Supply a fresh UUID `idempotencyKey` for each new logical refresh.
Reuse that key with identical inputs to recover the same accepted request. Do not generate a new request after an uncertain response.
Do not enable `force` without approval for its additional refresh scope and cost.

Preserve the accepted response's `dataRequest.id` and `dataRequest.nextOperations`.
Use the exact tool, operation, and input from `nextOperations.status` to poll.
When ready, use `nextOperations.result` once and cache the delivered result immediately.
Request Markdown on that delivery when useful.
Do not consume both the descriptor's result route and the legacy collection route for one job.
Do not retry delivery after success or `DATA_REQUEST_ALREADY_DELIVERED`.
Never infer a job ID from an idempotency key.

## Evidence limits

Post analysis exposes `common`, `subject`, and `templates`.
Templates can contain `steps`, `template`, `rationale`, and `placeholders`.
Steps can contain `name`, `description`, optional `template`, and optional `sourceText`.
Link analysis exposes `common` and `subject`. Post-style templates are not guaranteed.
Use the entity's `canonicalUrl` for its source link.
Post metrics use `observedAt`. Links use `lastObservedAt` and can report `analysisFreshness`.
Transcript metadata and media availability do not imply access to transcript text or downloadable media.