Letterby Docs

Tools

Every MCP tool, with its inputs, limits and errors.

The server exposes 12 tools. All of them read data. None of them write.

A client only sees the tools its scopes allow. All data belongs to the workspace you approved.

Account

ToolInputsReturnsScope
menoneThe team's id and name, and the scopes granted to this connection.none

Publications and offers

ToolInputsReturnsScope
list_publicationslimitYour publications, newest first.offers:read
get_publicationpublication_idOne publication.offers:read
list_offerspublication_id, limitThe offers a publication sponsors: status, payout, budgets and spend.offers:read
get_offerpublication_id, offer_idOne offer.offers:read
get_offer_statspublication_id, offer_idTotal spend, spend this month and the number of active agreements.offers:read
get_conversion_summaryoffer_id, start, endVerified, paid and reversed subscriber counts and spend for a date range.offers:read

get_conversion_summary covers the last 30 days by default. Pass start and end as ISO 8601 date-times to change the range, up to 366 days.

Agreements

ToolInputsReturnsScope
list_agreementspublication_id, limitThe offers a publication promotes, with status and accepted terms.agreements:read
get_agreementpublication_id, agreement_idOne agreement.agreements:read

Payouts and balance

ToolInputsReturnsScope
list_payoutslimitYour payouts, latest period first.payouts:read
get_payoutpayout_idOne payout with a line per offer.payouts:read
get_balancenoneBalance, reserved and available amounts.balance:read

Conventions

  • IDs are UUIDs.
  • Money is an integer number of cents, with a currency field.
  • Dates are ISO 8601 in UTC.
  • limit defaults to 50. The maximum is 100. List tools are not paginated.
  • Text written by other users, such as offer names and descriptions, is wrapped in <untrusted-content> tags. Assistants are told to treat it as data, not as instructions.

Limits

LimitValue
Tool calls30 per minute for each connection (one user, one workspace, one client)
Requests before sign-in120 per minute for each IP address
Calls in one batch20
Request body256 KB

Errors

Errors follow JSON-RPC 2.0. Each one carries data.request_id; quote it when you contact support.

CodeMessageMeaning
-32700parse_errorThe body is not valid JSON.
-32600invalid_request, batch_too_largeBad request shape, an empty batch, or more than 20 calls in a batch.
-32601method_not_foundUnknown method or tool, or a tool the connection has no scope for.
-32602invalid_paramsA tool argument is missing or invalid.
-32603internal_errorSomething failed on our side.
-32001missing_token, invalid_tokenNot signed in, or access expired or was revoked. HTTP 401.
-32004not_foundThe item does not exist or belongs to another team.
-32005rate_limitedToo many calls. Wait and retry.
-32006payload_too_largeThe request body is over 256 KB. HTTP 413.

Most errors arrive with HTTP 200 and the error in the JSON-RPC body. The per-IP limit is the exception: it returns HTTP 429 with a Retry-After header.

On this page