Define fixed read/write operations
Prepare a controlled test service: a Bearer-authenticated verification path, a read endpoint returning a known report, and a write endpoint storing reference/text that can be independently looked up by reference. Return JSON. Save this template as http-tool.json, replace the base_url placeholder and implement the endpoints first. These are not built-in Hexagon services... segments.
The adapter injects Bearer authorization and a stable call idempotency-key. Custom authentication-header mapping is not exposed here. Receiving that header does not prove upstream deduplication, so this example uses replay=never. Consider idempotency_key only after verifying real upstream deduplication. GET alone does not establish absence of side effects.
Review the mapping and replay contract
Forread_report, arguments {"id":"report-1"} become a query parameter on the fixed /reports/read path. A numeric or object argument is JSON-encoded as a query value, not expanded into path segments. For save_report, {"reference":"request-1","text":"Reviewed"} becomes the JSON body. No mapping step interpolates arbitrary arguments into the upstream host or authentication header.
In the current broker, an uncertain dispatched GET can be retried even when its operation says replay: never. The broker treats GET as replayable independently of the non-GET policy. Therefore only expose genuinely repeat-safe reads through GET; do not map a state-changing endpoint to GET and expect replay: never to prevent repetition. For POST, idempotency_key is appropriate only when the upstream actually honors the stable call key and preserves the same result across retries. Keep never for writes without that contract.
Connection verification may return sanitized account/scope display metadata from a small JSON response. Missing metadata remains unknown; the displayed scope does not replace the selected operation policy or approve a write. A successful verification endpoint also does not prove permission to every operation path.
Create, validate, enable, and bind
These local management examples read private credentials; see self-hosting for hosted initialization. Retain/reuse the returned ID.tools: {reports: connection_id} with a Tools-capable Harness, then preflight/create the Session. Required Tools need authorization during initialization. optional_tools does not bypass authorization or approval.
First call read_report and verify actual content. Then request save_report and inspect reference/text before approving. approval=true controls invocation approval independently of existing connection credentials. Confirm rejection causes zero upstream writes, then test one authorized write to a dedicated record. See approvals.
Responses and unknown outcomes
Requests time out after 20 seconds and reject redirects. 401/403 take the authentication-error path. Results must parse as JSON; response text exceeding 1048576 JavaScript code units fails. That check is not a byte-level download-limit guarantee. A remote write can succeed before its response is lost or fails parsing. A task error does not establish no side effect. Call records retain request hash and dispatched policy. Reconcile unknown outcomes instead of generating a new reference and repeating the business action. Inspect tool_calls / toolCalls, verify the original reference remotely, then use resolve_tool_call / resolveToolCall with completed/failed and evidence. Resolution does not send another remote request. Leave genuinely unknown outcomes waiting or cancel; do not invent success. Later connection edits cannot change the original call’s replay qualification. See reconciliation.Test a write by its business reference
Use a dedicated report reference such ashexagon-acceptance-001. The reference identifies the business record; the Tool call ID identifies one platform invocation. Preserve both. The following is an acceptance procedure for your controlled service, not an execution result from this documentation update.
If the service cannot query the reference or distinguish duplicate writes, it cannot support this reconciliation proof yet. Do not infer “not written” from a failed request, and do not reuse this procedure on production data. GET operations have the separate repeat-safe requirement described above. A direct protected HTTP binding bypasses ToolBroker approval, so it cannot substitute for the approved-write test.