webctx 0.2.5 → 0.2.6

package/README.md

@@ -10,7 +10,7 @@ webctx read-link <url>
 webctx map-site <url>
 webctx research "podcast conversations about AI agents"
 webctx inspect particle/podcasts/episodes/search
-webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}' --max-credits 20
+webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}'
 ```
 
 The output is plain text or markdown, so it is easy to hand to ChatGPT, Codex, Claude Code, a shell script, or another tool. Search now retrieves relevant source excerpts automatically instead of returning only URLs. For a specific URL, add an optional question to explore related documentation and surface exact code and API details.
@@ -37,10 +37,10 @@ webctx research "podcast conversations about AI agents" --limit 5
 webctx research --view sources --limit 5
 webctx research --mode catalogue --view operations --sources particle --limit 10
 webctx inspect particle/podcasts/episodes/search
-webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}' --max-credits 20
+webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}'
 ```
 
-Browse [the structured-data guide](https://webctx.ashray.xyz/docs/data-sources) for filters, paging, batches, full upstream responses, validation, and credit handling. Discovery/inspection is free; `execute` uses paid Alexandria credits. The per-request default preflight cap is 100 credits (configurable via `WEBCTX_ALEXANDRIA_MAX_CREDITS`). Third-party provider terms require separate human acceptance; Origo never accepts them automatically.
+Browse [the structured-data guide](https://webctx.ashray.xyz/docs/data-sources) for filters, paging, batches, full upstream responses, validation, and credit handling. Discovery/inspection is free; `execute` uses paid Alexandria credits. The hosted Origo server enforces a 200-credit limit per request, with no user-facing budget controls. Estimated and actual credits are shown in responses. Third-party provider terms require separate human acceptance; Origo never accepts them automatically.
 
 Origo deploys independently through the `origo-api` Vercel project on pushes to `main`. CLI releases and npm publishing are unchanged. See the [Origo MCP guide](https://webctx.ashray.xyz/docs/origo) for architecture, setup, and security notes.
 

package/internal/app/app.go

@@ -125,12 +125,8 @@ func Run(args []string, stdout, stderr io.Writer) int {
 		return 0
 	case "execute":
 		request := ExecuteDataInput{Raw: flags["raw"] == "true", RequestID: flags["request-id"]}
-		if flag := flags["max-credits"]; flag != "" {
-			n, e := strconv.Atoi(flag)
-			if e != nil {
-				return cliDataError(stderr, dataError("invalid_budget", "--max-credits requires an integer."))
-			}
-			request.MaxCredits = n
+		if _, supplied := flags["max-credits"]; supplied {
+			return cliDataError(stderr, dataError("unsupported_flag", "Credit limits are managed by the server; remove --max-credits."))
 		}
 		if jsonCalls := flags["calls"]; jsonCalls != "" {
 			data, e := cliJSONString(jsonCalls)
@@ -153,7 +149,7 @@ func Run(args []string, stdout, stderr io.Writer) int {
 			}
 			request.Calls = []DataCall{{ID: input, Inputs: inputs}}
 		} else {
-			return cliDataError(stderr, dataError("missing_calls", "Usage: webctx execute <operation-id> --inputs JSON [--max-credits N] or --calls JSON."))
+			return cliDataError(stderr, dataError("missing_calls", "Usage: webctx execute <operation-id> --inputs JSON or --calls JSON."))
 		}
 		result, e := ExecuteData(request)
 		if e != nil {
@@ -177,8 +173,8 @@ Usage:
   webctx map-site <url>
   webctx research [question] [--view sources|groups|operations] [--sources IDs] [--include inputs,output,examples] [--limit N] [--offset N]
   webctx inspect <operation-or-source-id> [--raw]
-  webctx execute <operation-id> --inputs '{"field":"value"}' [--max-credits N] [--request-id ID]
-  webctx execute --calls '[{"id":"source/operation","inputs":{}}]' [--max-credits N]
+  webctx execute <operation-id> --inputs '{"field":"value"}' [--request-id ID]
+  webctx execute --calls '[{"id":"source/operation","inputs":{}}]'
 
 Examples:
   webctx search "next.js server components"
@@ -187,7 +183,7 @@ Examples:
   webctx research "podcast conversations about AI agents"
   webctx research --view sources --limit 5
   webctx inspect particle/podcasts/episodes/search
-  webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}' --max-credits 20
+  webctx execute particle/podcasts/episodes/search --inputs '{"semantic_search":"AI agents","limit":2}'
   webctx read-link https://docs.example.com/guide
   webctx read-link https://docs.example.com/api --question "How do auth and pagination work?"
   webctx map-site https://example.com`, version)

package/internal/app/data_client.go

@@ -18,7 +18,10 @@ import (
 )
 
 const dataAPIBase = "https://api.firecrawl.dev/v2"
-const defaultDataCreditBudget = 100
+
+// The server, not a client-provided tool parameter, controls this preflight ceiling.
+// A production override is configured on the Origo Vercel project.
+const defaultDataCreditBudget = 200
 const maxDataResponseBytes int64 = 12 << 20
 
 type DataError struct {
@@ -43,21 +46,12 @@ func dataAPIKey() (string, error) {
 
 func dataCreditCap() int {
 	value, err := strconv.Atoi(strings.TrimSpace(os.Getenv("WEBCTX_ALEXANDRIA_MAX_CREDITS")))
-	if err != nil || value < 1 || value > 100000 {
+	if err != nil || value < 1 || value > defaultDataCreditBudget {
 		return defaultDataCreditBudget
 	}
 	return value
 }
 
-func paidDataEnabled() bool {
-	switch strings.ToLower(strings.TrimSpace(os.Getenv("WEBCTX_ALEXANDRIA_PAID"))) {
-	case "0", "false", "no", "off":
-		return false
-	default:
-		return true
-	}
-}
-
 var safeRequestID = regexp.MustCompile("^[A-Za-z0-9_-]{8,128}$")
 
 func newRequestID() (string, error) {

package/internal/app/data_examples.go

@@ -0,0 +1,112 @@
+package app
+
+import (
+	"regexp"
+	"strings"
+)
+
+var backtickedIdentifier = regexp.MustCompile("`([A-Za-z][A-Za-z0-9_/-]{1,30})`")
+
+// Upstream examples can legitimately be absent. Offer a clearly marked,
+// locally validated sample input without claiming it was published by the
+// provider or that it was executed.
+func contractExamples(contract map[string]any) any {
+	if published := contract["examples"]; published != nil {
+		if len(listField(published)) > 0 {
+			return published
+		}
+		if len(mapField(published)) > 0 {
+			return published
+		}
+	}
+	input, needed := nativeInputTemplate(contract)
+	fieldInfo := map[string]map[string]any{}
+	for _, v := range listField(contract["options"]) {
+		if field := mapField(v); field != nil {
+			fieldInfo[stringField(field["name"])] = field
+		}
+	}
+	for _, name := range needed {
+		field := fieldInfo[name]
+		if value, ok := sampleFieldValue(name, field); ok {
+			input[name] = value
+		}
+	}
+	// An illustrative example should not accidentally fetch huge datasets
+	// when copied verbatim. Users may adjust the inputs freely.
+	for _, name := range []string{"limit", "per_page", "page_size", "max_results", "count"} {
+		if n, ok := numberField(input[name]); ok && n > 5 {
+			input[name] = 5
+		}
+	}
+	if _, _, err := parseOperationID(stringField(contract["id"])); err != nil {
+		return nil
+	}
+	validation := validateDataInputs(contract, input)
+	example := map[string]any{
+		"kind":              "generated_from_inspected_schema",
+		"note":              "Illustrative Origo-generated inputs; not a published provider example or an executed query.",
+		"inputs":            input,
+		"valid_input_shape": validation == nil,
+	}
+	if validation != nil {
+		example["note"] = "Illustrative input template; fill required fields and check source-specific constraints before execution."
+		example["needs_input"] = needed
+	} else {
+		example["next"] = map[string]any{"tool": "execute", "arguments": map[string]any{
+			"calls": []any{map[string]any{"id": contract["id"], "inputs": input}},
+		}}
+	}
+	return []any{example}
+}
+
+func sampleFieldValue(name string, field map[string]any) (any, bool) {
+	if field == nil {
+		return nil, false
+	}
+	if values := listField(field["oneOf"]); len(values) > 0 {
+		for _, v := range values {
+			if v != nil && v != "" {
+				return v, true
+			}
+		}
+	}
+	if sample, ok := field["example"]; ok && sample != nil {
+		return sample, true
+	}
+	if samples := listField(field["examples"]); len(samples) > 0 && samples[0] != nil {
+		return samples[0], true
+	}
+	if v, ok := field["default"]; ok && v != nil {
+		return v, true
+	}
+	info := stringField(field["about"]) + " " + stringField(field["description"])
+	lower := strings.ToLower(name + " " + info)
+	switch {
+	case strings.Contains(name, "series_id") && strings.Contains(info, "CPIAUCSL"):
+		return "CPIAUCSL", true
+	case strings.Contains(name, "series_id") && strings.Contains(info, "UNRATE"):
+		return "UNRATE", true
+	case strings.Contains(name, "series_id") && strings.Contains(info, "GDP"):
+		return "GDP", true
+	case strings.Contains(lower, "semantic_search"):
+		return "AI agents", true
+	case name == "query" || name == "search" || name == "keyword_search":
+		return "example topic", true
+	case name == "url" || strings.HasSuffix(name, "_url"):
+		return "https://example.com", true
+	}
+	// Backticked descriptions sometimes contain sample codes or IDs.
+	if strings.Contains(lower, "id") || strings.Contains(lower, "code") {
+		for _, match := range backtickedIdentifier.FindAllStringSubmatch(info, 10) {
+			candidate := match[1]
+			if strings.Contains(candidate, "/") || strings.Contains(candidate, "_") {
+				continue
+			}
+			if len(candidate) >= 3 && !strings.EqualFold(candidate, "required") {
+				return candidate, true
+			}
+		}
+	}
+	return nil, false
+}

package/internal/app/data_execute.go

@@ -215,7 +215,7 @@ func expectedCallCredits(contract map[string]any, inputs map[string]any) (int, e
 	return int(math.Ceil(estimated)), nil
 }
 
-func continuationForDataResult(id string, originalInputs map[string]any, data any, maxCredits int) map[string]any {
+func continuationForDataResult(id string, originalInputs map[string]any, data any) map[string]any {
 	value := mapField(data)
 	if value == nil {
 		return nil
@@ -224,8 +224,7 @@ func continuationForDataResult(id string, originalInputs map[string]any, data an
 		if provider := stringField(next["provider"]); provider != "" {
 			if capability := stringField(next["capability"]); capability != "" {
 				return map[string]any{"tool": "execute", "arguments": map[string]any{
-					"calls":       []any{map[string]any{"id": provider + "/" + capability, "inputs": mapField(next["options"])}},
-					"max_credits": maxCredits,
+					"calls": []any{map[string]any{"id": provider + "/" + capability, "inputs": mapField(next["options"])}},
 				}}
 			}
 		}
@@ -245,16 +244,14 @@ func continuationForDataResult(id string, originalInputs map[string]any, data an
 			next["cursor"] = cursor
 		}
 		return map[string]any{"tool": "execute", "arguments": map[string]any{
-			"calls":       []any{map[string]any{"id": id, "inputs": next}},
-			"max_credits": maxCredits,
+			"calls": []any{map[string]any{"id": id, "inputs": next}},
 		}}
 	}
 	if page, ok := numberField(value["next_page"]); ok && page > 0 {
 		next := copyInputs(originalInputs)
 		next["page"] = int(page)
 		return map[string]any{"tool": "execute", "arguments": map[string]any{
-			"calls":       []any{map[string]any{"id": id, "inputs": next}},
-			"max_credits": maxCredits,
+			"calls": []any{map[string]any{"id": id, "inputs": next}},
 		}}
 	}
 	if offset, ok := numberField(value["next_offset"]); ok && offset >= 0 {
@@ -263,8 +260,7 @@ func continuationForDataResult(id string, originalInputs map[string]any, data an
 		if offset > previous {
 			next["offset"] = int(offset)
 			return map[string]any{"tool": "execute", "arguments": map[string]any{
-				"calls":       []any{map[string]any{"id": id, "inputs": next}},
-				"max_credits": maxCredits,
+				"calls": []any{map[string]any{"id": id, "inputs": next}},
 			}}
 		}
 	}
@@ -285,16 +281,7 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 	if len(input.Calls) == 0 || len(input.Calls) > 10 {
 		return nil, dataError("invalid_calls", "Provide 1-10 operation calls with id and inputs.")
 	}
-	if !paidDataEnabled() {
-		return nil, dataError("paid_data_disabled", "Paid data queries are disabled by WEBCTX_ALEXANDRIA_PAID=off.")
-	}
 	cap := dataCreditCap()
-	if input.MaxCredits > 0 && input.MaxCredits < cap {
-		cap = input.MaxCredits
-	}
-	if input.MaxCredits < 0 || input.MaxCredits > dataCreditCap() {
-		return nil, dataError("invalid_budget", fmt.Sprintf("max_credits must be between 1 and the configured maximum of %d.", dataCreditCap()))
-	}
 	if input.RequestID != "" && !safeRequestID.MatchString(input.RequestID) {
 		return nil, dataError("invalid_request_id", "request_id must have 8-128 letters, digits, hyphens or underscores.")
 	}
@@ -334,9 +321,9 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 		}
 		estimated += cost
 		if estimated > cap {
-			return nil, &DataError{Code: "credit_budget_exceeded",
-				Message: fmt.Sprintf("Preflight estimate %d credits exceeds the %d-credit request cap. Reduce calls/record limits, or configure WEBCTX_ALEXANDRIA_MAX_CREDITS.", estimated, cap),
-				Details: map[string]any{"estimated_credits": estimated, "max_credits": cap},
+			return nil, &DataError{Code: "server_credit_limit_exceeded",
+				Message: fmt.Sprintf("This request is estimated at %d credits, above Origo's %d-credit server limit. Reduce the number of operations or requested records.", estimated, cap),
+				Details: map[string]any{"estimated_credits": estimated, "server_credit_limit": cap},
 			}
 		}
 		provider, capability, _ := parseOperationID(call.ID)
@@ -360,7 +347,7 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 		if errorsAsData(err, &typed) {
 			typed.Details = map[string]any{"request_id": requestID,
 				"retry": map[string]any{"tool": "execute", "arguments": ExecuteDataInput{
-					Calls: input.Calls, MaxCredits: cap, RequestID: requestID, Raw: input.Raw,
+					Calls: input.Calls, RequestID: requestID, Raw: input.Raw,
 				}},
 			}
 		}
@@ -384,6 +371,9 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 			"data":         entry["data"],
 			"credits_used": entry["creditsCost"],
 		}
+		if explanation := dataMeasurementNote(entry["data"]); explanation != "" {
+			item["measurement_note"] = explanation
+		}
 		if token := entry["alexandriaId"]; token != nil {
 			item["data_id"] = token
 		}
@@ -391,7 +381,7 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 			item["error"] = errValue
 		}
 		if i < len(input.Calls) {
-			if next := continuationForDataResult(id, input.Calls[i].Inputs, entry["data"], cap); next != nil {
+			if next := continuationForDataResult(id, input.Calls[i].Inputs, entry["data"]); next != nil {
 				item["next"] = next
 			}
 		}
@@ -401,7 +391,7 @@ func ExecuteData(input ExecuteDataInput) (map[string]any, error) {
 		"results":           results,
 		"request_id":        requestID,
 		"estimated_credits": estimated,
-		"pricing_note":      "max_credits is a preflight estimate; actual per-record charges are determined by the upstream provider and the account's Firecrawl limits.",
+		"pricing_note":      "Estimated credits are calculated before execution; the upstream provider reports actual charges. Origo enforces a server-managed per-request credit limit.",
 		"guidance":          "Use next to fetch additional pages where available. Reuse request_id when retrying the same paid request, but generate a new ID for the next page.",
 	}
 	if cost := payload["creditsCost"]; cost != nil {
@@ -422,3 +412,24 @@ func errorsAsData(err error, into **DataError) bool {
 	}
 	return ok
 }
+
+// Interpret only well-defined provider unit codes, and distinguish CPI index
+// levels from annual inflation rates without transforming source values.
+func dataMeasurementNote(raw any) string {
+	data := mapField(raw)
+	if data == nil {
+		return ""
+	}
+	series := strings.ToUpper(stringField(data["series_id"]))
+	if !strings.HasPrefix(series, "CPI") {
+		return ""
+	}
+	switch strings.ToLower(stringField(data["units"])) {
+	case "lin", "":
+		return "CPI observations are price-index levels, not annual inflation percentages. Do not label them as inflation rates; a year-over-year percentage requires a 12-month comparison or an appropriate FRED transformation."
+	case "pc1":
+		return "FRED units=pc1 represents the percent change from one year ago, not an index level."
+	default:
+		return "CPI observations use the requested FRED units transformation; inspect the units field before interpreting values as percentages."
+	}
+}

package/internal/app/data_inspect.go

@@ -144,10 +144,8 @@ func InspectData(input InspectDataInput) (map[string]any, error) {
 	}
 	provider, _, _ := parseOperationID(id)
 	inputs, missing := nativeInputTemplate(item)
-	budget := dataCreditCap()
 	execArguments := map[string]any{
-		"calls":       []any{map[string]any{"id": id, "inputs": inputs}},
-		"max_credits": budget,
+		"calls": []any{map[string]any{"id": id, "inputs": inputs}},
 	}
 	response := map[string]any{
 		"id":           id,
@@ -161,7 +159,7 @@ func InspectData(input InspectDataInput) (map[string]any, error) {
 		},
 		"inputs":         map[string]any{"fields": item["options"], "requires_one_of": item["requiresOneOf"]},
 		"output":         item["response"],
-		"examples":       item["examples"],
+		"examples":       contractExamples(item),
 		"input_template": inputs,
 		"next":           map[string]any{"tool": "execute", "arguments": execArguments},
 		"guidance":       "Copy next.arguments into execute, fill any blank required inputs and adjust values according to inputs.fields. Execute uses credits.",

package/internal/app/data_research.go

@@ -1,6 +1,9 @@
 package app
 
-import "strings"
+import (
+	"sort"
+	"strings"
+)
 
 func researchView(view, query string) (string, error) {
 	switch strings.ToLower(strings.TrimSpace(view)) {
@@ -165,6 +168,20 @@ func ResearchData(input ResearchDataInput) (map[string]any, error) {
 		}
 		data := mapField(raw["data"])
 		items = listField(data["tools"])
+		// Some upstream ranked matches arrive out of order despite including a
+		// similarity score. Present the highest-scoring candidate first, retaining
+		// upstream order for exact ties or missing scores.
+		sort.SliceStable(items, func(i, j int) bool {
+			a, aok := numberField(mapField(items[i])["similarity"])
+			b, bok := numberField(mapField(items[j])["similarity"])
+			if aok != bok {
+				return aok
+			}
+			if !aok {
+				return false
+			}
+			return a > b
+		})
 		// Ranked search has no native cursor. Expose the free, complete
 		// catalogue with matching semantic query as an optional expansion.
 		next = map[string]any{"tool": "research", "arguments": map[string]any{

package/internal/app/data_tools_test.go

@@ -59,6 +59,18 @@ func (d *dataTestTransport) RoundTrip(req *http.Request) (*http.Response, error)
 		return testHTTPResponse(req, status, string(b), nil), nil
 	}
 	if req.URL.Path == "/v2/search" {
+		if strings.Contains(stringField(payload["query"]), "relevance ordering") {
+			low := dataTestContract()
+			low["id"] = "particle/podcasts/episodes/list"
+			low["similarity"] = 0.1
+			high := dataTestContract()
+			high["id"] = "particle/podcasts/episodes/search"
+			high["similarity"] = 0.97
+			middle := dataTestContract()
+			middle["id"] = "particle/podcasts/episode"
+			middle["similarity"] = 0.8
+			return write(200, map[string]any{"success": true, "data": map[string]any{"tools": []any{low, high, middle}}})
+		}
 		return write(200, map[string]any{"success": true, "data": map[string]any{
 			"tools": []any{dataTestContract()},
 		}})
@@ -115,6 +127,20 @@ func (d *dataTestTransport) RoundTrip(req *http.Request) (*http.Response, error)
 	return write(400, map[string]any{"success": false, "error": "Bad test request."})
 }
 
+func TestResearchSortsMatchesByActualSimilarity(t *testing.T) {
+	installDataTestTransport(t)
+	results, err := ResearchData(ResearchDataInput{Query: "relevance ordering", Limit: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := results["results"].([]map[string]any)
+	if found[0]["id"] != "particle/podcasts/episodes/search" ||
+		found[1]["id"] != "particle/podcasts/episode" ||
+		found[2]["id"] != "particle/podcasts/episodes/list" {
+		t.Fatalf("results were not ordered by reported relevance: %#v", found)
+	}
+}
+
 func installDataTestTransport(t *testing.T) *dataTestTransport {
 	t.Helper()
 	old := http.DefaultClient
@@ -122,7 +148,6 @@ func installDataTestTransport(t *testing.T) *dataTestTransport {
 	d := &dataTestTransport{}
 	http.DefaultClient = &http.Client{Transport: d}
 	t.Setenv("FIRECRAWL_API_KEY", "test-key")
-	t.Setenv("WEBCTX_ALEXANDRIA_PAID", "true")
 	t.Setenv("WEBCTX_ALEXANDRIA_MAX_CREDITS", "100")
 	return d
 }
@@ -155,6 +180,10 @@ func TestProgressiveDataDiscoveryAndExecution(t *testing.T) {
 	if len(listField(mapField(details["inputs"])["fields"])) != 4 {
 		t.Fatalf("missing upstream contract fields: %#v", details["inputs"])
 	}
+	generated := listField(details["examples"])
+	if len(generated) == 0 || mapField(generated[0])["valid_input_shape"] != true {
+		t.Fatalf("inspection must generate an explicitly labeled, schema-valid example: %#v", details["examples"])
+	}
 	continued := mapField(details["next"])
 	if continued["tool"] != "execute" {
 		t.Fatalf("no next execution: %#v", continued)
@@ -169,8 +198,7 @@ func TestProgressiveDataDiscoveryAndExecution(t *testing.T) {
 		t.Fatalf("invalid template: %#v", skeleton)
 	}
 	got, err := ExecuteData(ExecuteDataInput{
-		Calls:      []DataCall{{ID: id, Inputs: map[string]any{"semantic_search": "AI agents", "limit": float64(2)}}},
-		MaxCredits: 20,
+		Calls: []DataCall{{ID: id, Inputs: map[string]any{"semantic_search": "AI agents", "limit": float64(2)}}},
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -222,20 +250,18 @@ func TestCatalogueBrowsingReturnsExactPaginationCall(t *testing.T) {
 	}
 }
 
-func TestExecutionValidationAndBudgetRejectBeforePaidCall(t *testing.T) {
+func TestExecutionValidationAndServerLimitRejectBeforePaidCall(t *testing.T) {
 	mock := installDataTestTransport(t)
 	id := "particle/podcasts/episodes/search"
 	for _, testCase := range []struct {
-		inputs  map[string]any
-		credits int
-		code    string
+		inputs map[string]any
+		code   string
 	}{
-		{map[string]any{}, 20, "invalid_inputs"},
-		{map[string]any{"semantic_search": "AI agents", "limit": 101}, 20, "invalid_inputs"},
-		{map[string]any{"semantic_search": "AI agents", "unknown_field": 123}, 20, "invalid_inputs"},
-		{map[string]any{"semantic_search": "AI agents", "limit": 5}, 5, "credit_budget_exceeded"},
+		{map[string]any{}, "invalid_inputs"},
+		{map[string]any{"semantic_search": "AI agents", "limit": 101}, "invalid_inputs"},
+		{map[string]any{"semantic_search": "AI agents", "unknown_field": 123}, "invalid_inputs"},
 	} {
-		_, err := ExecuteData(ExecuteDataInput{Calls: []DataCall{{ID: id, Inputs: testCase.inputs}}, MaxCredits: testCase.credits})
+		_, err := ExecuteData(ExecuteDataInput{Calls: []DataCall{{ID: id, Inputs: testCase.inputs}}})
 		typed, ok := err.(*DataError)
 		if !ok || typed.Code != testCase.code {
 			t.Fatalf("wanted %s, got %v", testCase.code, err)
@@ -279,7 +305,7 @@ func TestCLIResearchAndInspectJSON(t *testing.T) {
 	if code := Run([]string{"inspect", "particle/podcasts/episodes/search"}, &out, &errBuf); code != 0 {
 		t.Fatalf("CLI inspect failed: %s", errBuf.String())
 	}
-	if !strings.Contains(out.String(), "semantic_search") || !strings.Contains(out.String(), "max_credits") {
+	if !strings.Contains(out.String(), "semantic_search") || strings.Contains(out.String(), "max_credits") {
 		t.Fatalf("CLI inspect omitted exact execute syntax: %s", out.String())
 	}
 }
@@ -287,7 +313,7 @@ func TestCLIResearchAndInspectJSON(t *testing.T) {
 func TestProviderNextOffsetCreatesCopyReadyContinuation(t *testing.T) {
 	id := "fred-stlouisfed-org/economic-data/series_observations"
 	inputs := map[string]any{"series_id": "CPIAUCSL", "limit": 2.0, "offset": 0.0}
-	next := continuationForDataResult(id, inputs, map[string]any{"next_offset": 2.0, "count": 956.0}, 15)
+	next := continuationForDataResult(id, inputs, map[string]any{"next_offset": 2.0, "count": 956.0})
 	if mapField(next)["tool"] != "execute" {
 		t.Fatalf("expected executable pagination: %+v", next)
 	}
@@ -334,3 +360,85 @@ func TestInspectOnlyOutputStillHasExecuteInputTemplate(t *testing.T) {
 		t.Fatalf("missing necessary next-call schema after include=output: %+v", details)
 	}
 }
+
+func TestServerManagedCreditCeilingCannotBeOverridden(t *testing.T) {
+	mock := installDataTestTransport(t)
+	// The ceiling defaults to 200 and an invalidly high environment value
+	// cannot silently widen it beyond 200.
+	t.Setenv("WEBCTX_ALEXANDRIA_MAX_CREDITS", "200")
+	if got := dataCreditCap(); got != 200 {
+		t.Fatalf("bad production cap: %d", got)
+	}
+	t.Setenv("WEBCTX_ALEXANDRIA_MAX_CREDITS", "2000")
+	if got := dataCreditCap(); got != 200 {
+		t.Fatalf("server cap exceeded 200: %d", got)
+	}
+	t.Setenv("WEBCTX_ALEXANDRIA_MAX_CREDITS", "120")
+	if got := dataCreditCap(); got != 120 {
+		t.Fatalf("server environment not respected: %d", got)
+	}
+	id := "particle/podcasts/episodes/search"
+	validInputs := map[string]any{"semantic_search": "AI agents"}
+	// 9*15=135: reject before ANY provider is queried.
+	batch := make([]DataCall, 9)
+	for i := range batch {
+		batch[i] = DataCall{ID: id, Inputs: validInputs}
+	}
+	_, err := ExecuteData(ExecuteDataInput{Calls: batch})
+	typed, ok := err.(*DataError)
+	if !ok || typed.Code != "server_credit_limit_exceeded" ||
+		mapField(typed.Details)["estimated_credits"] != 135 {
+		t.Fatalf("expected server-only limit, got %#v", err)
+	}
+	mock.mu.Lock()
+	defer mock.mu.Unlock()
+	if mock.executions != 0 {
+		t.Fatalf("server limit failed to prevent execution, calls=%d", mock.executions)
+	}
+}
+
+func TestClientCreditControlIsNotAvailableInCLI(t *testing.T) {
+	installDataTestTransport(t)
+	var stdout, stderr bytes.Buffer
+	code := Run([]string{"execute", "particle/podcasts/episodes/search", "--inputs", `{"semantic_search":"AI agents"}`, "--max-credits", "1"}, &stdout, &stderr)
+	if code != 1 || !strings.Contains(stderr.String(), `"code": "unsupported_flag"`) {
+		t.Fatalf("old client credit option should fail clearly, status=%d error=%s", code, stderr.String())
+	}
+}
+
+func TestCPIInterpretationDoesNotConfuseIndexWithInflation(t *testing.T) {
+	levels := dataMeasurementNote(map[string]any{"series_id": "CPIAUCSL", "units": "lin"})
+	if !strings.Contains(levels, "index levels") || !strings.Contains(levels, "not annual inflation percentages") {
+		t.Fatalf("CPI level explanation missing: %s", levels)
+	}
+	percentage := dataMeasurementNote(map[string]any{"series_id": "CPIAUCSL", "units": "pc1"})
+	if !strings.Contains(percentage, "percent change from one year ago") {
+		t.Fatalf("transformation note missing: %s", percentage)
+	}
+	if dataMeasurementNote(map[string]any{"series_id": "UNRATE", "units": "lin"}) != "" {
+		t.Fatal("unemployment must not get CPI-specific semantics")
+	}
+}
+
+func TestGeneratedFREDExampleUsesDocumentedSeries(t *testing.T) {
+	c := map[string]any{
+		"id": "fred-stlouisfed-org/economic-data/series_observations",
+		"options": []any{
+			map[string]any{"name": "series_id", "type": "string", "required": true, "about": "FRED series id, e.g. GDP, UNRATE and CPIAUCSL"},
+			map[string]any{"name": "limit", "type": "number", "default": 1000, "min": 1, "max": 10000},
+		},
+	}
+	examples := listField(contractExamples(c))
+	if len(examples) != 1 {
+		t.Fatalf("no fallback example: %#v", examples)
+	}
+	example := mapField(examples[0])
+	inputs := mapField(example["inputs"])
+	if example["kind"] != "generated_from_inspected_schema" || example["valid_input_shape"] != true ||
+		inputs["series_id"] != "CPIAUCSL" || inputs["limit"] != 5 {
+		t.Fatalf("unexpected generated FRED sample: %#v", examples)
+	}
+	if mapField(example["next"])["tool"] != "execute" {
+		t.Fatalf("generated example cannot be copied into execute: %#v", example)
+	}
+}

package/internal/app/data_types.go

@@ -33,8 +33,7 @@ type DataCall struct {
 // ExecuteDataInput supports up to ten calls in a single provider request.
 // It validates each call against the free catalogue before using credits.
 type ExecuteDataInput struct {
-	Calls      []DataCall `json:"calls" jsonschema:"One to ten operation calls; inspect each operation to discover exact input field names"`
-	MaxCredits int        `json:"max_credits,omitempty" jsonschema:"Maximum predicted credits for this request; defaults to WEBCTX_ALEXANDRIA_MAX_CREDITS or 100"`
-	RequestID  string     `json:"request_id,omitempty" jsonschema:"Optional stable idempotency identifier for retrying a paid request; reuse unchanged if retrying"`
-	Raw        bool       `json:"raw,omitempty" jsonschema:"Include the complete original provider response"`
+	Calls     []DataCall `json:"calls" jsonschema:"One to ten operation calls; inspect each operation to discover exact input field names"`
+	RequestID string     `json:"request_id,omitempty" jsonschema:"Optional stable idempotency identifier for retrying a paid request; reuse unchanged if retrying"`
+	Raw       bool       `json:"raw,omitempty" jsonschema:"Include the complete original provider response"`
 }

package/internal/app/research.go

@@ -87,6 +87,7 @@ func readLinkFocused(rawURL, question string, reader func(string) (string, error
 	if err != nil {
 		return "", err
 	}
+	primary = copyableCurlExamples(primary)
 
 	// Combine on-page links and authoritative Markdown index links instead of
 	// filling the entire budget from whichever links happen to appear first.
@@ -109,7 +110,11 @@ func readLinkFocused(rawURL, question string, reader func(string) (string, error
 		"**Source:** " + rawURL,
 		"",
 	}
-	primaryExcerpt := focusExcerpt(primary, question, focusedPrimaryBudget)
+	primaryBudget := focusedPrimaryBudget
+	if asksForAPIContracts(question) {
+		primaryBudget = 5300
+	}
+	primaryExcerpt := focusExcerpt(primary, question, primaryBudget)
 	parts = append(parts, primaryExcerpt)
 	successful := 1
 	relatedSuccessful := 0
@@ -124,7 +129,11 @@ func readLinkFocused(rawURL, question string, reader func(string) (string, error
 		relatedSuccessful++
 		seenURLs[source.url] = true
 		allRetrieved += "\n" + source.content
-		excerpt := focusExcerpt(source.content, question, relatedExcerptBudget(source.url))
+		relatedBudget := relatedExcerptBudget(source.url)
+		if asksForAPIContracts(question) && relatedBudget > 3000 {
+			relatedBudget = 3000
+		}
+		excerpt := focusExcerpt(copyableCurlExamples(source.content), question, relatedBudget)
 		outputEvidence += "\n" + excerpt
 		parts = append(parts, "", "## Related source", "**Source:** "+source.url, "", excerpt)
 	}
@@ -172,7 +181,11 @@ func readLinkFocused(rawURL, question string, reader func(string) (string, error
 			successful++
 			relatedSuccessful++
 			allRetrieved += "\n" + source.content
-			excerpt := focusExcerpt(source.content, question, relatedExcerptBudget(source.url))
+			followupBudget := relatedExcerptBudget(source.url)
+			if asksForAPIContracts(question) && followupBudget > 3000 {
+				followupBudget = 3000
+			}
+			excerpt := focusExcerpt(copyableCurlExamples(source.content), question, followupBudget)
 			outputEvidence += "\n" + excerpt
 			parts = append(parts, "", "## Supporting implementation reference", "**Source:** "+source.url, "", excerpt)
 		}
@@ -181,7 +194,10 @@ func readLinkFocused(rawURL, question string, reader func(string) (string, error
 		if contract := <-openAPIDone; contract.Content != "" {
 			successful++
 			outputEvidence += "\n" + contract.Content
-			parts = append(parts, "", "## REST API contract", "**Source:** "+contract.URL, "", contract.Content)
+			// Put exact REST contracts first so coding agents encounter the
+			// implementation-ready operations before lengthy source excerpts.
+			front := []string{"## REST API contract", "**Source:** " + contract.URL, "", contract.Content, ""}
+			parts = append(append(append([]string(nil), parts[:4]...), front...), parts[4:]...)
 		}
 	}
 	if structured := <-structuredDone; structured != "" {

package/internal/app/research_copyable.go

@@ -0,0 +1,48 @@
+package app
+
+import (
+	"encoding/json"
+	"regexp"
+	"strings"
+)
+
+var trailingPayloadSlash = regexp.MustCompile("(?m)\\\\[ \\t]*(\\r?\\n)")
+
+// Some source scrapers leave JavaScript-style line-continuation slashes
+// inside shell-quoted JSON. Those slashes make the published cURL request
+// uncopyable. Repair only payloads that are initially invalid JSON and become
+// valid JSON after removing those continuation markers. Label every repair.
+// The original source URL remains in the surrounding cited context.
+func copyableCurlExamples(markdown string) string {
+	parts := strings.Split(markdown, backtickFence)
+	if len(parts) < 3 {
+		return markdown
+	}
+	for i := 1; i < len(parts); i += 2 {
+		code := parts[i]
+		if !strings.Contains(code, "curl ") {
+			continue
+		}
+		start := strings.Index(code, "-d '{")
+		if start < 0 {
+			continue
+		}
+		bodyStart := start + len("-d '")
+		endRel := strings.LastIndex(code[bodyStart:], "}'")
+		if endRel < 0 {
+			continue
+		}
+		bodyEnd := bodyStart + endRel + 1
+		original := code[bodyStart:bodyEnd]
+		if json.Valid([]byte(original)) {
+			continue
+		}
+		fixed := trailingPayloadSlash.ReplaceAllString(original, "$1")
+		if fixed == original || !json.Valid([]byte(fixed)) {
+			continue
+		}
+		parts[i] = code[:bodyStart] + fixed + code[bodyEnd:]
+		parts[i-1] += "\n\n*[Copy-ready correction: removed stray line-continuation backslashes inside the published JSON payload; see the cited URL for the original.]*\n"
+	}
+	return strings.Join(parts, backtickFence)
+}

package/internal/app/research_copyable_test.go

@@ -0,0 +1,57 @@
+package app
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestMalformedAlexandriaJSONBecomesCopyable(t *testing.T) {
+	source := "# REST example\n" + backtickFence + "bash\n" +
+		"curl https://api.firecrawl.dev/v2/search \\\n" +
+		" -H 'Content-Type: application/json' \\\n" +
+		" -d '{\n  \"query\": \"podcast conversations\",\n  \"sources\": [\\\n    \"web\",\\\n    \"alexandria\"\\\n  ],\n  \"limit\": 2\n}'\n" +
+		backtickFence
+	got := copyableCurlExamples(source)
+	if !strings.Contains(got, "Copy-ready correction") {
+		t.Fatalf("lost truthful correction label: %s", got)
+	}
+	start := strings.Index(got, "-d '{")
+	if start < 0 {
+		t.Fatalf("lost source cURL: %s", got)
+	}
+	bodyStart := start + len("-d '")
+	bodyEnd := bodyStart + strings.LastIndex(got[bodyStart:], "}'") + 1
+	if !json.Valid([]byte(got[bodyStart:bodyEnd])) {
+		t.Fatalf("JSON request still uncopyable: %s", got[bodyStart:bodyEnd])
+	}
+	if !strings.Contains(got, " -H 'Content-Type: application/json' \\") {
+		t.Fatalf("source shell continuations should be preserved: %s", got)
+	}
+	if strings.Contains(got, "\"sources\": [\\") {
+		t.Fatalf("malformed JSON continuation not repaired: %s", got)
+	}
+	if copyableCurlExamples(got) != got {
+		t.Fatalf("correction should be idempotent")
+	}
+}
+
+func TestCorrectSourceExamplesAreNeverRewritten(t *testing.T) {
+	source := backtickFence + "bash\ncurl https://api.example.com/v2/search -d '{\"sources\":[\"alexandria\"]}'\n" + backtickFence
+	if got := copyableCurlExamples(source); got != source {
+		t.Fatalf("valid published snippet was modified: %s", got)
+	}
+}
+
+func TestRESTContractsLeadAndExcerptsStayConcise(t *testing.T) {
+	if focusedPrimaryBudget <= 5300 {
+		t.Fatal("REST excerpt budget should be narrower than normal focused context")
+	}
+	source := "# Official API docs\n" + strings.Repeat("Large unrelated introduction about navigation.\n", 700) +
+		"\n## REST API endpoint example\n" +
+		backtickFence + "bash\ncurl https://api.example.com/v2/search -d '{\"sources\":[\"alexandria\"]}'\n" + backtickFence
+	got := focusExcerpt(source, "What are the REST API endpoints and exact request examples?", 5300)
+	if len(got) > 6000 || !strings.Contains(got, "/v2/search") {
+		t.Fatalf("REST excerpt did not prioritize complete example under budget: len=%d", len(got))
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webctx",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Go CLI for agent-friendly web research, structured-data discovery, and source-native querying",
   "license": "MIT",
   "author": "amxv",

package/pkg/origo/data_test.go

@@ -49,17 +49,18 @@ func TestDataToolErrorsAreActionableStructuredMCPResults(t *testing.T) {
 		{"research", map[string]any{"view": "invalid"}, "invalid_view"},
 		{"inspect", map[string]any{"id": "not-a-valid-operation/"}, "invalid_operation"},
 		{"execute", map[string]any{"calls": []any{}}, "invalid_calls"},
+		{"execute", map[string]any{"calls": []any{map[string]any{"id": "example/data/list"}}, "max_credits": 1}, "invalid_arguments"},
 	} {
 		response := toolResponse(t, tc.name, tc.input, 11)
-		if response["isError"] != true {
-			t.Fatalf("%s should return isError: %#v", tc.name, response)
+		if response["isError"] == true {
+			t.Fatalf("%s should return normal structured response, not an MCP error: %#v", tc.name, response)
 		}
 		output, ok := response["structuredContent"].(map[string]any)
 		if !ok {
 			t.Fatalf("%s did not preserve structuredContent: %#v", tc.name, response)
 		}
 		errorResult, ok := output["error"].(map[string]any)
-		if !ok || errorResult["code"] != tc.code {
+		if !ok || errorResult["code"] != tc.code || output["ok"] != false {
 			t.Fatalf("%s error should be %s: %#v", tc.name, tc.code, response)
 		}
 	}
@@ -68,7 +69,6 @@ func TestDataToolErrorsAreActionableStructuredMCPResults(t *testing.T) {
 func TestDataToolResearchInspectExecuteOverHTTP(t *testing.T) {
 	t.Setenv("ORIGO_API_KEY", "secret")
 	t.Setenv("FIRECRAWL_API_KEY", "test")
-	t.Setenv("WEBCTX_ALEXANDRIA_PAID", "true")
 	original := http.DefaultClient
 	t.Cleanup(func() { http.DefaultClient = original })
 	var paidCount int
@@ -126,7 +126,7 @@ func TestDataToolResearchInspectExecuteOverHTTP(t *testing.T) {
 	}
 	result := toolResponse(t, "execute", map[string]any{"calls": []any{
 		map[string]any{"id": "example/data/list", "inputs": map[string]any{"query": "forty two"}},
-	}, "max_credits": 3}, 14)
+	}}, 14)
 	final := result["structuredContent"].(map[string]any)
 	if result["isError"] == true || final["credits_used"] != float64(2) || paidCount != 1 {
 		t.Fatalf("paid query failed: %#v calls=%d", final, paidCount)

package/pkg/origo/server.go

@@ -3,6 +3,7 @@
 package origo
 
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"crypto/subtle"
@@ -12,6 +13,7 @@ import (
 	"strings"
 
 	"github.com/amxv/webctx/pkg/retrieval"
+	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -50,42 +52,109 @@ func makeServer() *mcp.Server {
 		}
 		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: result}}}, nil, nil
 	})
-	mcp.AddTool(s, &mcp.Tool{
+	s.AddTool(&mcp.Tool{
 		Name:        "research",
 		Title:       "Find data sources",
 		Description: "Discover real-world information sources and their available operations. Search semantically, browse all sources, groups or operations, filter by websites/source IDs/categories, and paginate. Free; returns IDs and copy-ready inspect calls. Use read_link for regular documentation.",
 		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.ResearchInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Research(input)
-		return dataMCPResult(result, err)
-	})
-	mcp.AddTool(s, &mcp.Tool{
+		InputSchema: researchDataSchema(),
+	}, dataHandler(retrieval.Research))
+	s.AddTool(&mcp.Tool{
 		Name:        "inspect",
 		Title:       "Inspect a data source or operation",
 		Description: "Explore operations in a source, or inspect one operation's EXACT input types, required fields, constraints, output contract, pricing, and examples. Returns the next execute call with the exact input keys to fill. Free.",
 		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.InspectInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Inspect(input)
-		return dataMCPResult(result, err)
-	})
-	mcp.AddTool(s, &mcp.Tool{
+		InputSchema: inspectDataSchema(),
+	}, dataHandler(retrieval.Inspect))
+	s.AddTool(&mcp.Tool{
 		Name:        "execute",
 		Title:       "Query a data source (uses credits)",
-		Description: "Execute 1-10 inspected structured-data operations using their exact source IDs and inputs. Charges Firecrawl Alexandria credits after server-side schema and credit-budget checks. Supports pagination/continuations, stable request_id for safe retries, and original provider JSON. No third-party terms are accepted automatically.",
-		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: false, DestructiveHint: func() *bool { v := false; return &v }()},
-	}, func(_ context.Context, _ *mcp.CallToolRequest, input retrieval.ExecuteInput) (*mcp.CallToolResult, any, error) {
-		result, err := retrieval.Execute(input)
-		return dataMCPResult(result, err)
-	})
+		Description: "Execute 1-10 inspected structured-data operations using exact operation IDs and inputs. Alexandria credits are charged automatically; the server enforces its configured 200-credit per-request ceiling. Actual credits are reported. Supports pagination, safe request_id retries and provider-native JSON. Does not accept third-party terms.",
+		Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
+		InputSchema: executeDataSchema(),
+	}, dataHandler(retrieval.Execute))
 	return s
 }
 
+// Keep client-facing types narrow and self-describing. The SDK's default
+// reflection makes optional slices nullable and string enums unconstrained;
+// the catalogue operations support neither ambiguity.
+func researchDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.ResearchInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	schema.Properties["mode"].Enum = []any{"ranked", "catalogue"}
+	schema.Properties["view"].Enum = []any{"sources", "groups", "operations"}
+	for _, key := range []string{"mode", "view"} {
+		schema.Properties[key].Type = "string"
+		schema.Properties[key].Types = nil
+	}
+	for _, key := range []string{"urls", "sources", "categories", "groups", "operations", "include"} {
+		p := schema.Properties[key]
+		p.Type = "array"
+		p.Types = nil
+	}
+	schema.Properties["include"].Items.Enum = []any{"inputs", "output", "examples"}
+	return schema
+}
+
+func inspectDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.InspectInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	p := schema.Properties["include"]
+	p.Type = "array"
+	p.Types = nil
+	p.Items.Enum = []any{"inputs", "output", "examples"}
+	return schema
+}
+
+func executeDataSchema() *jsonschema.Schema {
+	schema, err := jsonschema.For[retrieval.ExecuteInput](nil)
+	if err != nil {
+		panic(err)
+	}
+	countMin, countMax := 1, 10
+	p := schema.Properties["calls"]
+	p.Type = "array"
+	p.Types = nil
+	p.MinItems = &countMin
+	p.MaxItems = &countMax
+	return schema
+}
+
+// Manual validation keeps data errors in successful MCP tool responses rather
+// than surfacing them as client-side INVALID_ARGUMENT tool exceptions.
+func dataHandler[In any](fn func(In) (map[string]any, error)) mcp.ToolHandler {
+	return func(_ context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		var input In
+		args := req.Params.Arguments
+		if len(args) == 0 {
+			args = []byte("{}")
+		}
+		decoder := json.NewDecoder(bytes.NewReader(args))
+		decoder.DisallowUnknownFields()
+		if err := decoder.Decode(&input); err != nil {
+			response, _, e := dataMCPResult(nil, &retrieval.DataError{Code: "invalid_arguments", Message: err.Error()})
+			return response, e
+		}
+		result, err := fn(input)
+		response, _, e := dataMCPResult(result, err)
+		return response, e
+	}
+}
+
 func dataMCPResult(result map[string]any, err error) (*mcp.CallToolResult, any, error) {
 	failed := err != nil
 	if failed {
 		// Use the shared error serializer to preserve codes, corrective details
 		// and provider-term acceptance URLs as structured tool output.
 		result = retrieval.DataErrorResult(err)
+		result["ok"] = false
+	} else {
+		result["ok"] = true
 	}
 	bytes, marshalErr := json.MarshalIndent(result, "", "  ")
 	if marshalErr != nil {
@@ -94,7 +163,9 @@ func dataMCPResult(result map[string]any, err error) (*mcp.CallToolResult, any,
 	return &mcp.CallToolResult{
 		Content:           []mcp.Content{&mcp.TextContent{Text: string(bytes)}},
 		StructuredContent: result,
-		IsError:           failed,
+		// Keep validation/provider failures in the structured result. Clients
+		// commonly convert isError=true to opaque INVALID_ARGUMENT exceptions.
+		IsError: false,
 	}, nil, nil
 }
 

package/pkg/origo/server_test.go

@@ -1,6 +1,7 @@
 package origo
 
 import (
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -22,6 +23,57 @@ func request(t *testing.T, key, body string) *httptest.ResponseRecorder {
 	return response
 }
 
+func TestDataSchemasExposeExactEnumsAndNonNullableCalls(t *testing.T) {
+	t.Setenv("ORIGO_API_KEY", "secret")
+	result := request(t, "secret", `{"jsonrpc":"2.0","id":12,"method":"tools/list","params":{}}`)
+	if result.Code != 200 {
+		t.Fatalf("tools/list failed: %s", result.Body.String())
+	}
+	var decoded struct {
+		Result struct {
+			Tools []struct {
+				Name        string         `json:"name"`
+				InputSchema map[string]any `json:"inputSchema"`
+				Annotations map[string]any `json:"annotations"`
+			} `json:"tools"`
+		} `json:"result"`
+	}
+	if err := json.Unmarshal(result.Body.Bytes(), &decoded); err != nil {
+		t.Fatal(err)
+	}
+	schemas := map[string]map[string]any{}
+	for _, tool := range decoded.Result.Tools {
+		if tool.Annotations["readOnlyHint"] != true {
+			t.Fatalf("%s was not marked read-only", tool.Name)
+		}
+		if _, exists := tool.Annotations["openWorldHint"]; exists {
+			t.Fatalf("%s should omit openWorldHint", tool.Name)
+		}
+		schemas[tool.Name] = tool.InputSchema
+	}
+	if len(schemas) != 5 {
+		t.Fatalf("expected five tools, got %d", len(schemas))
+	}
+	props := func(name string) map[string]any { return schemas[name]["properties"].(map[string]any) }
+	mode := props("research")["mode"].(map[string]any)
+	view := props("research")["view"].(map[string]any)
+	if mode["type"] != "string" || len(mode["enum"].([]any)) != 2 ||
+		view["type"] != "string" || len(view["enum"].([]any)) != 3 {
+		t.Fatalf("research discovery schemas are not typed: mode=%#v view=%#v", mode, view)
+	}
+	incl := props("research")["include"].(map[string]any)
+	if incl["type"] != "array" || len(incl["items"].(map[string]any)["enum"].([]any)) != 3 {
+		t.Fatalf("include does not constrain allowed options: %#v", incl)
+	}
+	calls := props("execute")["calls"].(map[string]any)
+	if _, present := props("execute")["max_credits"]; present {
+		t.Fatal("execute still exposes credit-budget control")
+	}
+	if calls["type"] != "array" || calls["minItems"] != float64(1) || calls["maxItems"] != float64(10) {
+		t.Fatalf("execute calls must be non-null and 1–10 items: %#v", calls)
+	}
+}
+
 func TestServerRequiresConfiguredKey(t *testing.T) {
 	t.Setenv("ORIGO_API_KEY", "")
 	response := request(t, "somekey", `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}`)
@@ -62,11 +114,11 @@ func TestFiveToolsWithProgressiveDataInterface(t *testing.T) {
 	if count := strings.Count(text, `"name":`); count != 5 {
 		t.Fatalf("expected exactly 5 tools, got %d: %s", count, text)
 	}
-	if count := strings.Count(text, `"readOnlyHint":true`); count != 4 {
-		t.Fatalf("expected the four free retrieval tools to be read-only, got %d: %s", count, text)
+	if count := strings.Count(text, `"readOnlyHint":true`); count != 5 {
+		t.Fatalf("expected all five MCP tools to declare readOnlyHint=true, got %d: %s", count, text)
 	}
-	if count := strings.Count(text, `"readOnlyHint":false`); count != 1 {
-		t.Fatalf("expected only paid execute to indicate effects on billing, got %d: %s", count, text)
+	if strings.Contains(text, `"readOnlyHint":false`) || strings.Contains(text, `"openWorldHint"`) || strings.Contains(text, `"destructiveHint"`) {
+		t.Fatalf("unexpected non-read-only or open-world/destructive annotations: %s", text)
 	}
 }
 

package/pkg/retrieval/data.go

@@ -6,6 +6,7 @@ type ResearchInput = app.ResearchDataInput
 type InspectInput = app.InspectDataInput
 type ExecuteInput = app.ExecuteDataInput
 type DataCall = app.DataCall
+type DataError = app.DataError
 
 func Research(input ResearchInput) (map[string]any, error) { return app.ResearchData(input) }
 func Inspect(input InspectInput) (map[string]any, error)   { return app.InspectData(input) }