MCP tools and responses
The public MCP interface is Toolora’s OAuth-protected /mcp endpoint on the API
host. The connected server’s tools/list defines the available names and argument
schemas. The generated Skill/catalogue and public contract explain their intended
use; a client should not reconstruct a tool call from a similar historical API.
The marketplace matching gateway and synthetic Project Studio server are separate
interfaces.
Discovery and authorization
Section titled “Discovery and authorization”Use the generated catalogue for tool names, versions, annotations and input fields.
Read toolora://contract/{tool_name} for the full evidence-envelope schema when
needed. Metadata, Skill, prompt and static app-resource reads do not all pass the
business gate. Business tools resolve the selected company and live person;
ordinary callers need projects:read, followed by narrower capability and resource
checks. Worker own-project permission alone does not admit the public business
surface. MCP authorization owns those detailed predicates.
Identity scopes such as email/optional openid are not business capabilities. The server currently disables SDK resource-audience validation and reuses incoming bearers on selected downstream paths. Current Supabase identity verification does not resolve that separate audience-boundary gap. Tool annotations describe intended effects; they are not permission checks or evidence that a human approved a write.
Structured response contract
Section titled “Structured response contract”| Field or block | Interpretation |
|---|---|
tool, tool_version |
Operation and response contract version |
as_of, data_freshness |
Observation time and the nature of that read/projection |
data, counts, found where supplied |
Returned business data and the result’s bounded meaning |
source_refs |
Traceable source identity; citations can be capped independently of rows |
missing_info, section_coverage |
Missing authority, data or verified coverage; absence is not zero |
truncation, page/section continuations |
What was bounded and how to obtain the next part |
| Binary resource blocks | Actual returned original bytes/parts; preserve them when displaying a document |
Unknown arguments or invalid types produce tool errors, normally with isError
and a classified error such as invalid_argument. A successful read can be empty
or have found=false. An empty page at an offset describes that page, not
necessarily the entire underlying register. A binary resource URI labels returned
content; it does not mint an independent reusable download grant.
Continuations and evidence
Section titled “Continuations and evidence”Follow the returned arguments rather than incrementing every cursor as if it were
an integer. Ordinary record/search lists use their page continuation; sectioned
results use pagination.<section>.next_arguments. Message text offsets count
characters; binary offsets count bytes. Search continuation preserves the ranking
of a bounded result set. Ordinary list offsets are not snapshot authority and can
see changed data on a later request.
sync_changes has a different checkpoint contract and no whole-company snapshot
mode. Change tracking explains its stable page size,
resynchronization and source coverage. Payment sections can be unavailable even
when invoices are readable. Only the relevant reconciliation evidence supports
an outstanding-balance conclusion.
Effect-bearing tools and recovery
Section titled “Effect-bearing tools and recovery”Quote proposals, invitation proposals, technical document jobs and quote-image receivers have different effects. Saving a proposal is not native quote creation, an invitation send or document approval; a technical job/image upload can still change technical state before human business confirmation. Follow proposal contracts and the returned confirmation link.
For synthetic Draft A, read its current reference/revision, submit the intended change with expected_revision and handle conflict by reloading. Do not claim a native quote or customer acceptance from a successful proposal response. For synthetic Original B, preserve every returned binary block and missing-coverage field instead of summarizing an unavailable part as an empty document.
The delivery PR records deterministic, substituted-client and reused local-stack evidence separately. Source review does not establish current OAuth issuance, client interoperability or provider outcomes beyond their named receipts.