Skip to content

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.

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.

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.

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.

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.