@zackbart/connecta 0.14.2 → 0.15.0

package/dist/validate.js

@@ -7,6 +7,17 @@ import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
 // connector are collectable, the same pattern compactSchema uses.
 const validators = new WeakMap();
 const REQUIRED_PROPERTY_RE = /^Instance does not have required property "([^"]+)"\.$/;
+const CONTAINER_VALIDATION_KEYWORDS = new Set([
+    "properties",
+    "items",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "if",
+    "not",
+    "patternProperties",
+    "additionalProperties",
+]);
 function decodePointerPart(value) {
     return value.replaceAll("~1", "/").replaceAll("~0", "~");
 }
@@ -31,6 +42,85 @@ function argumentPath(location) {
         return "/";
     return location.startsWith("#") ? location.slice(1) || "/" : "/";
 }
+function validationUnitKey(unit) {
+    return JSON.stringify([
+        unit.keyword,
+        unit.keywordLocation,
+        unit.instanceLocation,
+        unit.error,
+    ]);
+}
+function childPropertyName(parentLocation, childLocation) {
+    const prefix = parentLocation === "#" ? "#/" : `${parentLocation}/`;
+    if (!childLocation.startsWith(prefix))
+        return undefined;
+    const encoded = childLocation.slice(prefix.length);
+    return !encoded.includes("/") ? decodePointerPart(encoded) : undefined;
+}
+function schemaDeclaresProperty(schema, property) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+        return false;
+    }
+    const record = schema;
+    const properties = record.properties;
+    if (properties !== null &&
+        typeof properties === "object" &&
+        !Array.isArray(properties) &&
+        Object.hasOwn(properties, property)) {
+        return true;
+    }
+    const patterns = record.patternProperties;
+    if (patterns === null ||
+        typeof patterns !== "object" ||
+        Array.isArray(patterns)) {
+        return false;
+    }
+    for (const pattern of Object.keys(patterns)) {
+        try {
+            if (new RegExp(pattern).test(property))
+                return true;
+        }
+        catch {
+            // The validator owns schema support. An unusable pattern cannot prove
+            // that this additional-properties branch is a duplicate.
+        }
+    }
+    return false;
+}
+function isDuplicateAdditionalPropertiesBranch(schema, units, index) {
+    const unit = units[index];
+    const wrapper = units[index - 1];
+    if (unit?.keyword !== "false" ||
+        wrapper?.keyword !== "additionalProperties" ||
+        !wrapper.keywordLocation.endsWith("/additionalProperties")) {
+        return false;
+    }
+    const property = childPropertyName(wrapper.instanceLocation, unit.instanceLocation);
+    if (property === undefined)
+        return false;
+    const parentSchemaLocation = wrapper.keywordLocation.slice(0, -"/additionalProperties".length);
+    return schemaDeclaresProperty(pointerValue(schema, parentSchemaLocation || "#"), property);
+}
+function normalizedValidationUnits(schema, units) {
+    const seen = new Set();
+    return units.filter((unit, index) => {
+        if (CONTAINER_VALIDATION_KEYWORDS.has(unit.keyword))
+            return false;
+        if (isDuplicateAdditionalPropertiesBranch(schema, units, index)) {
+            return false;
+        }
+        const key = validationUnitKey(unit);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function agentFacingValidationError(unit) {
+    return unit.keyword === "false"
+        ? "Value is not allowed by the declared schema."
+        : unit.error;
+}
 function expectedType(schema, unit) {
     if (unit.keyword === "type") {
         const value = pointerValue(schema, unit.keywordLocation);
@@ -66,19 +156,8 @@ function expectedType(schema, unit) {
     return fixed[unit.keyword];
 }
 function validationDetails(schema, units) {
-    const leafUnits = units.filter((unit) => ![
-        "properties",
-        "items",
-        "allOf",
-        "anyOf",
-        "oneOf",
-        "if",
-        "not",
-        "patternProperties",
-        "additionalProperties",
-    ].includes(unit.keyword));
     const issues = [];
-    for (const unit of leafUnits) {
+    for (const unit of units) {
         const missing = unit.keyword === "required"
             ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1]
             : undefined;
@@ -164,12 +243,13 @@ export function validateToolInput(schema, args, opts) {
         return opts.failClosed ? unevaluableSchema(opts.address) : null;
     }
     if (result && !result.valid) {
-        const units = result.errors.filter((u) => u.instanceLocation !== "#");
-        const detail = (units.length > 0 ? units : result.errors)
-            .slice(0, 3)
-            .map((u) => `${u.instanceLocation}: ${u.error}`)
+        const units = normalizedValidationUnits(schema, result.errors);
+        const nestedUnits = units.filter((unit) => unit.instanceLocation !== "#");
+        const detail = (nestedUnits.length > 0 ? nestedUnits : units)
+            .slice(0, MAX_ARGUMENT_VALIDATION_ISSUES)
+            .map((unit) => `${unit.instanceLocation}: ${agentFacingValidationError(unit)}`)
             .join("; ");
-        return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation: validationDetails(schema, result.errors) });
+        return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation: validationDetails(schema, units) });
     }
     return null;
 }

package/dist/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.14.2";
+export declare const CONNECTA_VERSION = "0.15.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.14.2";
+export const CONNECTA_VERSION = "0.15.0";
 //# sourceMappingURL=version.js.map

package/documentation/code-mode.md

@@ -219,21 +219,21 @@ const page = await connecta.search({
 });
 ```
 
-**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes; capped shapes remain structurally valid with `unknown` types plus `/* truncated */`, and carry `inputSchemaTruncated` or `outputSchemaTruncated`. Use `connecta.describe` (or JSON search) for omitted exact constraints.
+**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Top-level `search_tools` is different: it returns `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`. Complete matches normally precede partial matches, but a partial candidate whose complete normalized tool name occurs in the normalized raw query competes by score; conversational cleanup applies only to scoring terms. Other candidates covering at least two terms fill the page after every complete match; when no complete match exists, the existing any-term fallback remains. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Tool rows expose neither lexical scores nor per-result coverage. An empty or whitespace-only query browses. Non-empty input with no ASCII lexical terms returns no tools and bounded no-match analysis; mixed input searches with its ASCII terms. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes. Each enum node gets 256 of those bytes. About three near-cap enum nodes can therefore coexist while leaving the final quarter for surrounding syntax; the unchanged global fallback still applies above 1,024 bytes. A capped enum preserves whole values before `unknown` and an exact omitted-value count, while an empty enum renders as `never`. Either cap carries `inputSchemaTruncated` or `outputSchemaTruncated`; a shape-wide cap remains structurally valid with `unknown` types plus `/* truncated */`. Small enums remain complete. Use `connecta.describe` (or JSON search) for omitted exact constraints.
 
 **S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
-**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`:
-the same names the rendered schema shows, ready to check before
-building arguments. Match inputs, truncation, safety, and outputs, not lexical
+**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`: the same names the rendered schema shows, ready to check before building arguments. Match inputs, truncation, safety, and outputs, not lexical
 rank; search distinct operations separately and use `outputKeys`, not guessed roots. A non-object schema — a union, an array, an
 unresolvable `$ref` — carries no lists rather than empty ones, because absent
 means "read the schema" where `[]` would claim the tool takes no fields. The
 lists come from the same walk that renders the compact schema, so a top-level
 `$ref` resolves and an `allOf` composes rather than reporting an empty list
-beside a schema that plainly shows fields; an object with no properties is the
-one case where `[]` is the truth. A truncated schema omits the corresponding
-key list rather than repeating a large partial inventory. `search_tools`
+beside a schema that plainly shows fields. A zero-input object keeps `inputKeys:
+[]` and `requiredInputKeys: []`; an output object with no declared properties
+omits `outputKeys` because it declares no useful inventory. A
+truncated schema omits the corresponding key list rather than repeating a
+large partial inventory. `search_tools`
 carries the same metadata whenever schemas are requested. Code-mode callers
 can set `includeSchemaKeys: false` to buy the bytes back.
 
@@ -384,7 +384,7 @@ type beats keeping the prose.
 
 **E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. Both the message and the derived `query` clamp the address to 512 UTF-8 bytes with a `…` marker: the address is caller-authored and lands in the message, the query, the text content, and `structuredContent`, so an invented 50 KB one would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake; a short one — the common case — is exact and untagged.
 
-**E8.** A remote MCP tool whose advertised schema rejects the call fails before provider dispatch with `invalid_args`, carrying bounded, value-free `{ path, code, expected }` findings and scoped search recovery keyed `function: "connecta.search"` like every other in-program miss. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
+**E8.** A remote MCP tool whose advertised schema rejects the call fails before provider dispatch with `invalid_args`, carrying bounded, value-free `{ path, code, expected }` findings and scoped search recovery keyed `function: "connecta.search"` like every other in-program miss. A declared property reports the schema keyword that failed, never the validator's duplicate `additionalProperties` branch; a truly undeclared property still reports `additionalProperties`. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
 
 ## Results and projection
 
@@ -840,7 +840,7 @@ the upstream `Executor` shape assignable.
 | `A3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (colliding alias) |
 | `A4` | `test/execute.test.ts` (namespace collisions, reserved namespace) |
 | `A5` | verdict; `A1`–`A3` are its enforcement |
-| `S1`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, and the unfiltered browse that replaces `list_connectors`), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`) |
+| `S1`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, and the unfiltered browse that replaces `list_connectors`), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools.test.ts` (mixed complete/partial ranking and stable pagination) |
 | `S3` | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound) |
 | `S4` | `test/guest-api-contract.test.ts` (unknown address in `describe`) |
 | `S5` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`) |

package/documentation/meta-tools.md

@@ -46,6 +46,18 @@ read-only calls and returns typed outcomes, and an unfiltered
 `connecta.search({})` browses every catalog a program can reach. Live connector
 probing is an operator concern: the operator pages and `/health` own it.
 
+The three discovery routes use deliberately different envelopes. These are
+their smallest successful one-tool shapes:
+
+```js
+// Top-level search_tools
+{ connectors: [{ id: "ci", tools: [{ name: "get_run", address: "ci.get_run" }] }], total: 1, offset: 0, limit: 8, hasMore: false }
+
+// Inside execute_code
+{ tools: [{ name: "get_run", address: "ci.get_run" }], total: 1, offset: 0, limit: 8, hasMore: false } // connecta.search
+{ tools: [{ name: "get_run", address: "ci.get_run", inputSchema: "{ runId: integer }" }] } // connecta.describe
+```
+
 ## Discovery context
 
 Start an unknown-address lookup with two to four distinctive action/object
@@ -60,8 +72,10 @@ or setting it to `"all"`, preserves the complete configured catalog. This is
 only a discovery filter: it neither grants authority nor changes invocation admission.
 `includeSchemas: "compact"` adds each match's input and any declared output
 shape. Bounded plain-object schemas also expose `inputKeys`,
-`requiredInputKeys`, and `outputKeys`; a truncated shape omits its corresponding
-list rather than repeating a large partial inventory. Matches carry declared
+`requiredInputKeys`, and `outputKeys`; a zero-input object keeps
+`requiredInputKeys: []`, while an output object with no declared properties
+omits `outputKeys`. A truncated shape omits its corresponding list rather than
+repeating a large partial inventory. Matches carry declared
 behavior annotations. Lexical rank is only one signal: select a candidate whose
 required inputs are available, whose schema is complete enough for the call,
 and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
@@ -75,11 +89,17 @@ Compact search is deliberately a routing view, not a second copy of connector
 documentation. Tool purposes are capped at 160 characters, connector
 descriptions and property prose are omitted, required input fields render
 before optional ones, and each input or output shape is capped at 1,024 UTF-8
-bytes. A capped object becomes a valid required-first shape with `unknown`
-types; other shapes become `unknown /* truncated */`. The match also carries
+bytes. Within that unchanged total, each enum node may spend at most 256 UTF-8
+bytes. This lets about three near-cap enum nodes coexist while reserving the
+remaining quarter for surrounding syntax; the global fallback still applies
+when the complete shape exceeds 1,024 bytes. A large enum keeps the longest
+whole-value prefix that fits, then adds `unknown` and a comment with the exact
+omitted-value count. An empty enum renders as the valid `never` type. A capped
+object becomes a valid required-first shape with `unknown` types; other shapes
+become `unknown /* truncated */`. Either cap marks the match with
 `inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
 `includeSchemas: "json"` or use the existing describe path when exact
-constraints matter.
+constraints matter. Small enums and both exact paths remain complete.
 
 ## Connector guide selection
 
@@ -176,13 +196,34 @@ set of inflectional variants preserves singular/plural and verb-form recall
 without allowing arbitrary mid-word substring matches. Ranking weights each
 query term by its document frequency across the available catalogs in that
 search, so a rare domain term outranks a ubiquitous action while action terms
-still distinguish `get`, `list`, `search`, and write operations. If no tool
-covers every non-conversational term, the same scorer falls back to any-term
-matching and marks the result `matchMode: "partial"`.
-
-Every partial or no-match lexical search also returns bounded `queryAnalysis`;
-an all-term result needs no recovery advice. `representedTerms` occur in the
-current page, `otherResultTerms` occur only in another result, and
+still distinguish `get`, `list`, `search`, and write operations. The scorer
+always evaluates useful near-matches instead of letting one broad all-term
+description hide them. Complete matches rank before ordinary partial matches;
+a partial candidate whose complete normalized tool name occurs in the
+normalized raw query competes with complete matches by score, and other
+candidates covering at least two terms fill the remaining page after them.
+Conversational cleanup applies only to scoring terms, never to the exact-name
+phrase check. If no tool covers every non-conversational term, the same scorer
+preserves the wider any-term fallback and marks the result
+`matchMode: "partial"`.
+
+Returned tool rows expose neither lexical scores nor per-result query coverage.
+The mixed complete/partial scorer still ranks rare domain terms, action terms,
+and exact tool-name phrases. Select from the returned purpose, address, schema,
+safety, and output shape. Page-level `queryAnalysis` remains the recovery path
+when no single result covers every term or no match exists.
+
+Only an empty or whitespace-only query browses. A non-empty query that
+normalizes to no ASCII lexical terms returns no tools instead of unrelated
+browse results. Its bounded `queryAnalysis.unmatchedTerms` contains the clipped
+raw query and guidance asks for ASCII action/object terms. A mixed query still
+searches with its ASCII terms; unsupported characters do not become false
+matches or per-tool coverage terms.
+
+Every partial or no-match lexical search also returns bounded page-level
+`queryAnalysis`; an all-term result needs no recovery advice.
+`representedTerms` occur in the current page, `otherResultTerms` occur only in
+another result, and
 `unmatchedTerms` have no lexical match in the catalogs that answered. Partial
 results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
@@ -331,7 +372,9 @@ exist. `nextAction` points to discovery scoped to the same connector and tool
 name when the compact schema is needed — routed like any other miss, so a
 program is sent to `connecta.search` and a top-level call to `search_tools` —
 while `retry` says to correct the listed arguments and reissue the original
-operation. A schema the local
+operation. A declared property reports only its failed schema keyword, while a
+truly undeclared property reports `additionalProperties`; validator-internal
+duplicate `additionalProperties` branches never reach the caller. A schema the local
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.

package/ethos.md

@@ -91,6 +91,7 @@ proposing one without a new argument is not.
 | `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove; a program can shrink anything ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Stabilized workflows (programs → versioned scripts/skills) | gated | earns a surface only once real traffic shows programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
 | Semantic tool search | gated | keyword search has not been shown to be the thing failing; earns its way in through [#222](https://github.com/zackbart/connecta/issues/222)'s harness ([#27](https://github.com/zackbart/connecta/issues/27)) |
+| Per-result lexical query coverage | removed | verbose, indexed, and trailing shapes did not earn their response-token cost: the coverage-off arm beat the verbose wire, the first compact wire regressed efficiency, and the trailing wire failed its precommitted 30-run clean-route gate (13/30 vs 9/30, +13.3 pp, Fisher p=0.422); preserve the mixed complete/partial ranking from [#326](https://github.com/zackbart/connecta/issues/326), but do not revive serialized coverage without new causal evidence ([#322](https://github.com/zackbart/connecta/issues/322), [#323](https://github.com/zackbart/connecta/issues/323)) |
 | MRTR / `input_required` passthrough | gated | statelessly relayable via `requestState`, but no host or downstream emits it yet; fails loudly until adoption evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size; paging on a polling extension adds round trips for nothing ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | fixed TTL + fingerprint is battle-tested and catalog reads are ~3 ms; earns its way in with refresh-churn evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/src/catalog-service.ts

@@ -45,11 +45,29 @@ export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
-const MAX_QUERY_ANALYSIS_TERMS = 8;
-const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
+const MAX_QUERY_TERMS = 8;
+const MAX_QUERY_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
+/** Clip one echoed query term without splitting a non-BMP code point. */
+function boundedQueryTerm(term: string): {
+  text: string;
+  truncated: boolean;
+} {
+  const characters: string[] = [];
+  for (const character of term) {
+    characters.push(character);
+    if (characters.length > MAX_QUERY_TERM_LENGTH) {
+      return {
+        text: `${characters.slice(0, MAX_QUERY_TERM_LENGTH - 1).join("")}…`,
+        truncated: true,
+      };
+    }
+  }
+  return { text: characters.join(""), truncated: false };
+}
+
 /**
  * The discovery route a routing failure should send a caller back through. Same
  * catalog logic serves both the top-level `search_tools` path and the
@@ -261,7 +279,9 @@ function schemaKeyMetadata(
           requiredInputKeys: inputKeys.required,
         }
       : {}),
-    ...(outputKeys ? { outputKeys: outputKeys.properties } : {}),
+    ...(outputKeys && outputKeys.properties.length > 0
+      ? { outputKeys: outputKeys.properties }
+      : {}),
   };
 }
 
@@ -647,6 +667,9 @@ export class CatalogService {
       tool: ToolDef;
       score: number;
       order: number;
+      exactName: boolean;
+      matchedTermCount: number;
+      complete: boolean;
     }> = [];
     let matchMode: "all" | "partial" = "all";
     const statistics = lexicalCorpusStatistics(
@@ -655,8 +678,19 @@ export class CatalogService {
       ),
       retrievalQuery,
     );
+    const trimmedQuery = query.trim();
+    const isBrowse = trimmedQuery.length === 0;
+    const queryTerms = lexicalQueryTerms(retrievalQuery);
+    const queryTermCount = queryTerms.length;
+    const unsearchableQuery = !isBrowse && queryTermCount === 0;
+    const analysisTerms = unsearchableQuery ? [trimmedQuery] : queryTerms;
+    const analyzedTerms = analysisTerms.slice(0, MAX_QUERY_TERMS);
+    const displayTerm = (term: string) => boundedQueryTerm(term).text;
+    const queryMetadataTruncated =
+      analysisTerms.length > analyzedTerms.length ||
+      analyzedTerms.some((term) => boundedQueryTerm(term).truncated);
     const collectMatches = (mode: "all" | "partial") => {
-      matches.length = 0;
+      const collected: typeof matches = [];
       let orderBase = 0;
       searchableCatalogs.forEach((catalog, connectorIndex) => {
         const connector = connectors[connectorIndex];
@@ -669,25 +703,59 @@ export class CatalogService {
             retrievalQuery,
             mode,
             statistics,
+            query,
           )) {
-            matches.push({
+            collected.push({
               connector,
               tool: ranked.tool,
               score: ranked.score,
               order: orderBase + ranked.order,
+              exactName: ranked.exactName,
+              matchedTermCount: ranked.matchedTermCount,
+              complete:
+                isBrowse || ranked.matchedTermCount === queryTermCount,
             });
           }
         }
         orderBase +=
           catalog.status === "fulfilled" ? catalog.value.length : 1;
       });
+      return collected;
     };
-    collectMatches("all");
-    if (query.trim() && matches.length === 0) {
+    // A non-empty query that normalizes to no lexical terms is not a browse.
+    // Ranking an empty phrase would otherwise return every tool as an
+    // unrelated zero-score match, with no coverage to explain the result.
+    const rankedMatches = unsearchableQuery
+      ? []
+      : collectMatches(isBrowse ? "all" : "partial");
+    const completeMatchCount = rankedMatches.filter(
+      (match) => match.complete,
+    ).length;
+    matches.push(
+      ...rankedMatches.filter(
+        (match) =>
+          match.complete ||
+          completeMatchCount === 0 ||
+          match.exactName ||
+          match.matchedTermCount >= 2,
+      ),
+    );
+    if (!isBrowse && !unsearchableQuery && completeMatchCount === 0) {
       matchMode = "partial";
-      collectMatches(matchMode);
     }
-    matches.sort((a, b) => b.score - a.score || a.order - b.order);
+    // Complete matches and exact tool-name phrases share the first rank tier.
+    // This lets a strong action/object name beat a weak description-only
+    // decoy. Other partial matches fill the remaining page only after every
+    // complete match, regardless of a rare-term score spike.
+    matches.sort((a, b) => {
+      const aFirstTier = a.complete || a.exactName;
+      const bFirstTier = b.complete || b.exactName;
+      return (
+        Number(bFirstTier) - Number(aFirstTier) ||
+        b.score - a.score ||
+        a.order - b.order
+      );
+    });
     const pageMatches = matches.slice(offset, offset + limit);
     const entries = pageMatches.map((match) => {
       const input = match.tool.inputSchema ?? { type: "object" };
@@ -769,12 +837,6 @@ export class CatalogService {
       offset + entries.length < matches.length
         ? offset + entries.length
         : undefined;
-    const queryTerms = lexicalQueryTerms(retrievalQuery);
-    const analyzedTerms = queryTerms.slice(0, MAX_QUERY_ANALYSIS_TERMS);
-    const displayTerm = (term: string) =>
-      term.length <= MAX_QUERY_ANALYSIS_TERM_LENGTH
-        ? term
-        : `${term.slice(0, MAX_QUERY_ANALYSIS_TERM_LENGTH - 1)}…`;
     const pageTools = new Set(pageMatches.map((match) => match.tool));
     const matchingTools = (term: string) =>
       new Set([
@@ -844,19 +906,24 @@ export class CatalogService {
       args.connector && !scopedConnector
         ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
         : undefined;
-    // Term-bearing searches report analysis only when the scorer had to
-    // degrade; a browse has no terms to analyse and normally reports none at
-    // all. But neither "this catalog is unavailable" nor "there is no such
-    // connector" is a statement about terms, and answering either browse with
-    // an empty entry list alone is indistinguishable from a connector that
-    // simply exposes no tools. The term partitions stay empty on those paths
-    // because there were no terms — the scope fields carry the whole message.
+    // Searchable queries report analysis when the scorer had to degrade. A
+    // non-empty query with no searchable terms reports the bounded raw input
+    // as unmatched instead of silently becoming a browse. A real browse has
+    // no terms to analyse and normally reports none at all. Scope failures are
+    // the exception, because an empty result alone looks like a connector that
+    // correctly exposes no tools.
     const reportsQueryAnalysis =
-      queryTerms.length > 0
+      unsearchableQuery ||
+      (queryTerms.length > 0
         ? matchMode === "partial"
-        : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0;
+        : unknownConnectorGuidance !== undefined || unavailableCatalogs > 0);
     const guidance =
-      queryTerms.length === 0
+      unsearchableQuery
+        ? (unknownConnectorGuidance ??
+          (scopedConnector && unavailableCatalogs > 0
+            ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Inspect catalogError for the typed reason and recovery detail.`
+            : "The query contained no searchable lexical terms. Use 2–4 ASCII action/object terms, or browse with an empty query."))
+        : queryTerms.length === 0
         ? // A browse has no terms to advise about, so it stays silent unless
           // the scope itself failed: the guidance on a scoped miss recommends
           // browsing with an empty query, and that advice must not lead into a
@@ -901,10 +968,7 @@ export class CatalogService {
               representedTerms,
               otherResultTerms,
               unmatchedTerms,
-              ...(queryTerms.length > analyzedTerms.length ||
-              analyzedTerms.some(
-                (term) => term.length > MAX_QUERY_ANALYSIS_TERM_LENGTH,
-              )
+              ...(queryMetadataTruncated
                 ? { truncated: true as const }
                 : {}),
               ...(args.connector ? { connectorScope: args.connector } : {}),