@modelprofile.com/flexharness 10.14.0 → 10.15.1

package/ts/classes.toolcatalog.ts

@@ -57,6 +57,7 @@ interface IMethodEntry {
   readonly summary: string;
   readonly description?: string;
   readonly tags: readonly string[];
+  readonly aliases: readonly string[];
   readonly examples: readonly string[];
   readonly input: ICatalogSchema;
   readonly inputScope: ISchemaScope;
@@ -68,7 +69,10 @@ interface IMethodEntry {
 }
 
 interface ITypeEntry {
+  /** The identifier the type is declared under. */
   readonly name: string;
+  /** The catalog's name for the type, where it is no identifier; `$ref`s name the type by it. */
+  readonly schemaName?: string;
   readonly description?: string;
   readonly declaration?: string;
   /** A catalog type's schema. */
@@ -107,17 +111,28 @@ const reservedWords = new Set([
 const controlPattern = /[\u0000-\u001f\u007f]/;
 const definitionRefPattern = /^#\/(\$defs|definitions)\/([^/]+)$/;
 const declaredTypesHeader = '// Declares types: ';
+const declaredTypesLine = /^\/\/ Declares types: (.*)$/gm;
 const identifierScanPattern = /[A-Za-z_$][A-Za-z0-9_$]*/g;
 const methodKeys = new Set([
-  'method', 'summary', 'description', 'tags', 'examples', 'inputSchema', 'outputSchema', 'declaration', 'run', 'onCall',
+  'method', 'summary', 'description', 'tags', 'aliases', 'examples', 'inputSchema', 'outputSchema', 'declaration', 'run', 'onCall',
 ]);
-const catalogKeys = new Set(['methods', 'types', 'onProposals']);
+const catalogKeys = new Set(['methods', 'types', 'vocabulary', 'onProposals']);
 const typeKeys = new Set(['name', 'description', 'schema', 'declaration']);
 const stopWords = new Set([
-  'a', 'an', 'and', 'are', 'all', 'as', 'be', 'by', 'for', 'from', 'get', 'i', 'in', 'is', 'it', 'me', 'my',
+  'a', 'an', 'and', 'are', 'all', 'as', 'be', 'by', 'for', 'from', 'i', 'in', 'is', 'it', 'me', 'my',
   'of', 'on', 'or', 'that', 'the', 'this', 'to', 'with',
 ]);
-const fieldWeights = { name: 3, namespace: 1.5, summary: 2, tags: 2, description: 1 } as const;
+const fieldWeights = { name: 3, aliases: 3, namespace: 1.5, summary: 2, tags: 2, description: 1 } as const;
+/**
+ * A method whose name's, or one alias's, every word the query names ranks this much higher: it is
+ * what was asked for.
+ */
+const nameCoverageFactor = 1.5;
+/**
+ * A top match leads clearly when it is the only one, or when the query names it and it scores this
+ * many times the runner-up.
+ */
+const clearMatchMargin = 1.25;
 type TSearchField = keyof typeof fieldWeights;
 const bm25K1 = 1.2;
 const bm25B = 0.75;
@@ -216,6 +231,13 @@ const searchTerms = (text: string): string[] => text
   .filter(Boolean)
   .map(stem);
 
+/** The search terms of a name or an alias, which must have some to be matched at all. */
+const namedTermsOf = (text: string, label: string): string[] => {
+  const terms = searchTerms(text);
+  if (terms.length === 0) throw new FlexHarnessValidationError(`${label} must contain a letter or digit.`);
+  return terms;
+};
+
 const editDistance = (left: string, right: string, limit: number): number => {
   if (Math.abs(left.length - right.length) > limit) return limit + 1;
   let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
@@ -301,6 +323,25 @@ const textOf = (
   return value;
 };
 
+/** Optional text: absent, or a string that is empty or blank, counts as not given. */
+const optionalTextOf = (
+  value: unknown,
+  label: string,
+  options: { maxCharacters?: number; maxBytes?: number; singleLine?: boolean },
+): string | undefined => value === undefined || (typeof value === 'string' && !value.trim())
+  ? undefined
+  : textOf(value, label, options);
+
+/**
+ * The identifier a catalog type is declared under: its name where that is one, else the name with
+ * each character an identifier cannot hold replaced by `_`, a leading digit or a reserved word
+ * escaped with `_`.
+ */
+const typeIdentifierOf = (name: string): string => {
+  const identifier = name.replace(/[^A-Za-z0-9_]/g, '_').replace(/^(?=\d)/, '_');
+  return reservedWords.has(identifier) ? `${identifier}_` : identifier;
+};
+
 const textListOf = (
   value: unknown,
   label: string,
@@ -314,6 +355,30 @@ const textListOf = (
   return value.map((entry, index) => textOf(entry, `${label}[${index}]`, options));
 };
 
+/** A vocabulary alias and the catalog words a query that says it searches for as well. */
+interface IVocabularyEntry {
+  readonly alias: readonly string[];
+  readonly words: readonly string[];
+}
+
+const vocabularyOf = (value: unknown): IVocabularyEntry[] => {
+  if (value === undefined) return [];
+  if (!isPlainObject(value)) {
+    throw new FlexHarnessValidationError('A tool catalog vocabulary must be a plain object of words and their aliases.');
+  }
+  const words = Object.entries(value);
+  if (words.length > limits.maxVocabularyWords) {
+    throw new FlexHarnessValidationError(`A tool catalog vocabulary must have at most ${limits.maxVocabularyWords} words.`);
+  }
+  const textOptions = { maxCharacters: limits.maxAliasCharacters, singleLine: true };
+  return words.flatMap(([word, aliases]) => {
+    const label = `Tool catalog vocabulary word "${word}"`;
+    const terms = namedTermsOf(textOf(word, label, textOptions), label);
+    return textListOf(aliases, `${label} aliases`, limits.maxAliases, textOptions)
+      .map((alias, index) => ({ alias: namedTermsOf(alias, `${label} aliases[${index}]`), words: terms }));
+  });
+};
+
 async function resolveCatalogSchema(schema: unknown, label: string): Promise<ICatalogSchema> {
   let json: unknown;
   let validate: TValidate | undefined;
@@ -355,10 +420,14 @@ async function resolveCatalogSchema(schema: unknown, label: string): Promise<ICa
 class CatalogSearchIndex {
   private readonly postings = new Map<string, Array<{ index: number; weight: number }>>();
   private readonly idf = new Map<string, number>();
+  /** The terms of each method's name and of each of its aliases. */
+  private readonly nameTerms: ReadonlyArray<ReadonlyArray<readonly string[]>>;
 
-  constructor(private readonly entries: readonly IMethodEntry[]) {
+  constructor(private readonly entries: readonly IMethodEntry[], private readonly vocabulary: readonly IVocabularyEntry[]) {
+    this.nameTerms = entries.map((entry) => [entry.name, ...entry.aliases].map((name) => [...new Set(searchTerms(name))]));
     const fieldTexts = (entry: IMethodEntry): Record<TSearchField, string[]> => ({
       name: searchTerms(entry.name),
+      aliases: entry.aliases.flatMap(searchTerms),
       namespace: searchTerms(entry.namespace),
       summary: searchTerms(entry.summary),
       tags: entry.tags.flatMap(searchTerms),
@@ -393,11 +462,21 @@ class CatalogSearchIndex {
     }
   }
 
-  /** Methods ranked by BM25 over name, namespace, summary, tags and description. */
-  public search(query: string, accept: (entry: IMethodEntry) => boolean): IMethodEntry[] {
-    const allTerms = [...new Set(searchTerms(query))];
+  /**
+   * Methods ranked by BM25 over name, aliases, namespace, summary, tags and description, best first.
+   * The query searches for the catalog words of every vocabulary alias it says as well.
+   */
+  public search(
+    query: string,
+    accept: (entry: IMethodEntry) => boolean,
+  ): Array<{ entry: IMethodEntry; score: number; named: boolean }> {
+    const said = new Set(searchTerms(query));
+    const allTerms = [...said];
+    for (const { alias, words } of this.vocabulary) {
+      if (alias.every((term) => said.has(term))) allTerms.push(...words);
+    }
     const meaningful = allTerms.filter((term) => !stopWords.has(term));
-    const terms = meaningful.length > 0 ? meaningful : allTerms;
+    const terms = [...new Set(meaningful.length > 0 ? meaningful : allTerms)];
     const scores = new Map<number, number>();
     for (const term of terms) {
       const idf = this.idf.get(term);
@@ -407,20 +486,23 @@ class CatalogSearchIndex {
       }
     }
     const exact = query.trim().toLowerCase();
+    const queryTerms = new Set(allTerms);
     return [...scores.entries()]
       .map(([index, score]) => {
         const entry = this.entries[index];
-        const bonus = entry.path.toLowerCase() === exact || entry.name.toLowerCase() === exact ? 1000 : 0;
-        return { entry, score: score + bonus };
+        const bonus = [entry.path, entry.name, ...entry.aliases].some((name) => name.toLowerCase() === exact) ? 1000 : 0;
+        const named = this.nameTerms[index].some((name) => name.every((term) => queryTerms.has(term)));
+        return { entry, score: (named ? score * nameCoverageFactor : score) + bonus, named };
       })
       .filter(({ entry }) => accept(entry))
-      .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path))
-      .map(({ entry }) => entry);
+      .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path));
   }
 }
 
 class FlexToolCatalogCore {
   public readonly renderedMethods = new Map<string, IRenderedDeclaration>();
+  /** The named types each rendered method's parameters and result use. */
+  public readonly methodTypeSets = new Map<string, { input: string[]; output: string[] }>();
   public readonly renderedTypes = new Map<string, IRenderedDeclaration>();
   public readonly validators = new Map<string, plugins.JsonSchemaValidator>();
   public readonly selfContainedInputs = new Map<string, TJsonSchemaNode>();
@@ -430,9 +512,12 @@ class FlexToolCatalogCore {
     public readonly mode: TDeclarationMode,
     public readonly methods: ReadonlyMap<string, IMethodEntry>,
     public readonly types: ReadonlyMap<string, ITypeEntry>,
+    /** The identifier of each catalog type, by the name its `$ref`s use. */
+    public readonly typeIdentifiers: ReadonlyMap<string, string>,
+    vocabulary: readonly IVocabularyEntry[],
     public readonly onProposals: IFlexToolCatalog['onProposals'] | undefined,
   ) {
-    this.index = new CatalogSearchIndex([...methods.values()]);
+    this.index = new CatalogSearchIndex([...methods.values()], vocabulary);
   }
 
   public static async build(catalog: unknown, mode: TDeclarationMode): Promise<FlexToolCatalogCore> {
@@ -443,19 +528,47 @@ class FlexToolCatalogCore {
     if (onProposals !== undefined && typeof onProposals !== 'function') {
       throw new FlexHarnessValidationError('A tool catalog onProposals must be a function.');
     }
+    const vocabulary = vocabularyOf(catalog.vocabulary);
     if (!Array.isArray(catalog.methods) || catalog.methods.length > limits.maxMethods) {
       throw new FlexHarnessValidationError(`Tool catalog methods must be an array with at most ${limits.maxMethods} entries.`);
     }
     if (catalog.types !== undefined && (!Array.isArray(catalog.types) || catalog.types.length > limits.maxTypes)) {
       throw new FlexHarnessValidationError(`Tool catalog types must be an array with at most ${limits.maxTypes} entries.`);
     }
-    const catalogTypes = new Map<string, ITypeEntry>();
+    const namedTypes = new Map<string, ITypeEntry>();
     for (const [index, type] of ((catalog.types ?? []) as unknown[]).entries()) {
       const entry = await FlexToolCatalogCore.normalizeType(type, `Tool catalog type ${index}`);
-      if (catalogTypes.has(entry.name)) {
+      if (namedTypes.has(entry.name)) {
         throw new FlexHarnessValidationError(`Tool catalog type "${entry.name}" is defined twice.`);
       }
-      catalogTypes.set(entry.name, entry);
+      namedTypes.set(entry.name, entry);
+    }
+    // A name that is an identifier keeps it; the others are mapped in code-point order, so a
+    // catalog always declares the same identifiers.
+    const typeIdentifiers = new Map<string, string>();
+    const taken = new Set<string>();
+    const names = [...namedTypes.keys()].sort(compareCodePoints);
+    for (const name of names) {
+      if (typeIdentifierOf(name) !== name) continue;
+      typeIdentifiers.set(name, name);
+      taken.add(name);
+    }
+    for (const name of names) {
+      if (typeIdentifiers.has(name)) continue;
+      const base = typeIdentifierOf(name);
+      let identifier = base;
+      for (let suffix = 2; taken.has(identifier); suffix++) identifier = `${base}_${suffix}`;
+      typeIdentifiers.set(name, identifier);
+      taken.add(identifier);
+    }
+    /** Catalog types by the name their `$ref`s use. */
+    const catalogTypes = new Map<string, ITypeEntry>();
+    for (const [name, entry] of namedTypes) {
+      const identifier = typeIdentifiers.get(name)!;
+      if (entry.declaration !== undefined && !new RegExp(`\\b(?:interface|type|enum|class)\\s+${identifier}\\b`).test(entry.declaration)) {
+        throw new FlexHarnessValidationError(`Tool catalog type "${name}" declaration must declare "${identifier}".`);
+      }
+      catalogTypes.set(name, { ...entry, name: identifier, ...(identifier === name ? {} : { schemaName: name }) });
     }
     const methodInputs: Array<Omit<IMethodEntry, 'inputScope' | 'outputScope'>> = [];
     for (const [index, method] of (catalog.methods as unknown[]).entries()) {
@@ -476,7 +589,7 @@ class FlexToolCatalogCore {
       }
     }
 
-    const registry = new Map<string, ITypeEntry>(catalogTypes);
+    const registry = new Map<string, ITypeEntry>([...catalogTypes.values()].map((type) => [type.name, type]));
     const canonicalDefinitions = new Map<string, string>();
     const scopeOf = (root: TJsonSchemaNode, label: string, requireSchemas: boolean): ISchemaScope => {
       const scope: ISchemaScope = { root, localNames: new Map() };
@@ -507,7 +620,10 @@ class FlexToolCatalogCore {
     };
     for (const type of catalogTypes.values()) {
       if (!type.schema) continue;
-      registry.set(type.name, { ...type, scope: scopeOf(type.schema.json, `Tool catalog type "${type.name}"`, true) });
+      registry.set(type.name, {
+        ...type,
+        scope: scopeOf(type.schema.json, `Tool catalog type "${type.schemaName ?? type.name}"`, true),
+      });
     }
     const methods = new Map<string, IMethodEntry>();
     for (const method of methodInputs) {
@@ -524,6 +640,8 @@ class FlexToolCatalogCore {
       mode,
       methods,
       types,
+      typeIdentifiers,
+      vocabulary,
       onProposals === undefined
         ? undefined
         : (proposals, context) => (onProposals as NonNullable<IFlexToolCatalog['onProposals']>).call(catalog, proposals, context),
@@ -535,21 +653,16 @@ class FlexToolCatalogCore {
     const unsupported = Object.keys(value).find((key) => !typeKeys.has(key));
     if (unsupported) throw new FlexHarnessValidationError(`${label} does not support "${unsupported}".`);
     const name = textOf(value.name, `${label} name`, { maxCharacters: limits.maxIdentifierCharacters, singleLine: true });
-    if (!typeNamePattern.test(name) || reservedWords.has(name)) {
-      throw new FlexHarnessValidationError(`${label} name must be an identifier that is not a reserved word.`);
-    }
+    if (/\s/.test(name)) throw new FlexHarnessValidationError(`${label} name must not contain whitespace.`);
     if (value.schema === undefined && value.declaration === undefined) {
       throw new FlexHarnessValidationError(`Tool catalog type "${name}" needs a schema or a declaration.`);
     }
-    const description = value.description === undefined
-      ? undefined
-      : textOf(value.description, `Tool catalog type "${name}" description`, { maxBytes: limits.maxDescriptionBytes });
+    const description = optionalTextOf(value.description, `Tool catalog type "${name}" description`, {
+      maxBytes: limits.maxDescriptionBytes,
+    })?.trim();
     const declaration = value.declaration === undefined
       ? undefined
       : textOf(value.declaration, `Tool catalog type "${name}" declaration`, { maxBytes: limits.maxDeclarationBytes });
-    if (declaration !== undefined && !new RegExp(`\\b(?:interface|type|enum|class)\\s+${name}\\b`).test(declaration)) {
-      throw new FlexHarnessValidationError(`Tool catalog type "${name}" declaration must declare "${name}".`);
-    }
     const schema = value.schema === undefined
       ? undefined
       : await resolveCatalogSchema(value.schema, `Tool catalog type "${name}" schema`);
@@ -594,12 +707,16 @@ class FlexToolCatalogCore {
     const summary = textOf(value.summary, `${methodLabel} summary`, {
       maxCharacters: limits.maxSummaryCharacters, singleLine: true,
     }).trim();
-    const description = value.description === undefined
-      ? undefined
-      : textOf(value.description, `${methodLabel} description`, { maxBytes: limits.maxDescriptionBytes }).trim();
+    const description = optionalTextOf(value.description, `${methodLabel} description`, {
+      maxBytes: limits.maxDescriptionBytes,
+    })?.trim();
     const tags = textListOf(value.tags, `${methodLabel} tags`, limits.maxTags, {
       maxCharacters: limits.maxTagCharacters, singleLine: true,
     });
+    const aliases = textListOf(value.aliases, `${methodLabel} aliases`, limits.maxAliases, {
+      maxCharacters: limits.maxAliasCharacters, singleLine: true,
+    });
+    aliases.forEach((alias, index) => namedTermsOf(alias, `${methodLabel} aliases[${index}]`));
     const examples = textListOf(value.examples, `${methodLabel} examples`, limits.maxExamples, {
       maxBytes: limits.maxExampleBytes,
     });
@@ -636,6 +753,7 @@ class FlexToolCatalogCore {
       summary,
       ...(description ? { description } : {}),
       tags: Object.freeze(tags),
+      aliases: Object.freeze(aliases),
       examples: Object.freeze(examples),
       input,
       ...(output ? { output } : {}),
@@ -688,7 +806,7 @@ class FlexToolCatalogCore {
         const local = scope.localNames.get(`${match[1]}/${key}`);
         if (local) return local;
         if (resolvePointer(scope.root, ref) !== undefined) return undefined;
-        return this.types.has(key) ? key : undefined;
+        return this.typeIdentifiers.get(key);
       },
       resolve: (ref: string): TJsonSchemaNode | undefined => {
         const target = resolvePointer(scope.root, ref);
@@ -702,12 +820,17 @@ class FlexToolCatalogCore {
     if (cached) return cached;
     const type = this.types.get(name)!;
     let rendered: IRenderedDeclaration;
+    const schemaNote = type.schemaName === undefined ? undefined : `Named "${type.schemaName}" in the schema.`;
     if (type.declaration !== undefined) {
-      rendered = { text: type.declaration.trim(), types: this.scanTypes(type.declaration, name) };
+      rendered = {
+        text: `${schemaNote === undefined ? '' : docBlock(schemaNote, '')}${type.declaration.trim()}`,
+        types: this.scanTypes(type.declaration, name),
+      };
     } else {
       const schema = type.definition ?? type.schema!.json;
       const writer = new SchemaDeclarationWriter(this.scopeContext(type.scope!));
-      const text = writer.namedDeclaration(name, schema, type.description);
+      const description = [type.description, schemaNote].filter((part) => part !== undefined).join('\n\n');
+      const text = writer.namedDeclaration(name, schema, description || undefined);
       rendered = { text, types: writer.usedTypes.filter((used) => used !== name) };
     }
     this.renderedTypes.set(name, rendered);
@@ -720,6 +843,9 @@ class FlexToolCatalogCore {
     let rendered: IRenderedDeclaration;
     if (entry.declaration !== undefined) {
       rendered = { text: entry.declaration.trim(), types: this.scanTypes(entry.declaration) };
+      // A host's declaration text does not tell parameters from the result: every type it names is
+      // declared with it.
+      this.methodTypeSets.set(entry.path, { input: rendered.types, output: [] });
     } else {
       const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
       const members = inputWriter.objectMembers(entry.input.json);
@@ -744,6 +870,10 @@ class FlexToolCatalogCore {
         text: `${docBlock(lines.join('\n'), '')}${signature}`,
         types: [...new Set([...inputWriter.usedTypes, ...(outputWriter?.usedTypes ?? [])])].sort(compareCodePoints),
       };
+      this.methodTypeSets.set(entry.path, {
+        input: [...new Set(inputWriter.usedTypes)].sort(compareCodePoints),
+        output: [...new Set(outputWriter?.usedTypes ?? [])].sort(compareCodePoints),
+      });
     }
     this.renderedMethods.set(entry.path, rendered);
     return rendered;
@@ -757,6 +887,28 @@ class FlexToolCatalogCore {
     return [...found].sort(compareCodePoints);
   }
 
+  /** The named types a method's parameters and result use. */
+  public methodTypes(entry: IMethodEntry): { input: string[]; output: string[] } {
+    this.renderMethod(entry);
+    return this.methodTypeSets.get(entry.path)!;
+  }
+
+  /** `names` and the types they use up to `depth` levels, `names` being the first, sorted. */
+  public typeLevels(names: Iterable<string>, depth: number, stop: ReadonlySet<string> = new Set()): string[] {
+    const result = new Set<string>();
+    let level = [...names];
+    for (let current = 0; current < depth && level.length > 0; current++) {
+      const next: string[] = [];
+      for (const name of level) {
+        if (result.has(name) || stop.has(name) || !this.types.has(name)) continue;
+        result.add(name);
+        next.push(...this.renderType(name).types);
+      }
+      level = next;
+    }
+    return [...result].sort(compareCodePoints);
+  }
+
   /** `names` and every type they use, transitively, sorted. */
   public typeClosure(names: Iterable<string>, stop: ReadonlySet<string> = new Set()): string[] {
     const result = new Set<string>();
@@ -783,7 +935,8 @@ class FlexToolCatalogCore {
         const ref = queue.pop()!;
         const match = definitionRefPattern.exec(ref);
         if (!match || resolvePointer(root, ref) !== undefined) continue;
-        const type = this.types.get(decodePointerToken(match[2]));
+        const identifier = this.typeIdentifiers.get(decodePointerToken(match[2]));
+        const type = identifier === undefined ? undefined : this.types.get(identifier);
         if (!type?.schema) continue;
         const container = (isSchemaRecord(root[match[1]]) ? root[match[1]] : (root[match[1]] = {})) as Record<string, unknown>;
         container[decodePointerToken(match[2])] = withoutDraft(structuredClone(type.schema.json) as TJsonSchemaNode);
@@ -821,6 +974,10 @@ export class FlexToolCatalog<TScope = unknown> {
     private readonly admitted: ReadonlySet<string> | undefined,
     /** The limits of `run_code`; absent while code mode is off. */
     public readonly codeMode: Readonly<IFlexCodeModeLimits> | undefined,
+    /** Levels of a result's named types a TypeScript declaration declares. */
+    private readonly outputTypeDepth: number,
+    /** `search` follows a clear top match with its declaration. */
+    private readonly describeTopMatch: boolean,
   ) {}
 
   /**
@@ -846,7 +1003,13 @@ export class FlexToolCatalog<TScope = unknown> {
       core = FlexToolCatalogCore.build(catalog, mode);
       byMode.set(mode, core);
     }
-    return new FlexToolCatalog<TScope>(await core, undefined, normalized.codeMode);
+    return new FlexToolCatalog<TScope>(
+      await core,
+      undefined,
+      normalized.codeMode,
+      normalized.outputTypeDepth,
+      normalized.describeTopMatch,
+    );
   }
 
   /** Every method path this catalog offers, sorted. */
@@ -866,6 +1029,8 @@ export class FlexToolCatalog<TScope = unknown> {
       this.core,
       new Set([...this.core.methods.keys()].filter((path) => allowed.has(path) && this.isAdmitted(path))),
       this.codeMode,
+      this.outputTypeDepth,
+      this.describeTopMatch,
     );
   }
 
@@ -887,6 +1052,7 @@ export class FlexToolCatalog<TScope = unknown> {
           'name, summary and description; `namespace` (a dotted path) narrows the search or, without `query`, lists',
           `the namespace like ls. Read a method's ${typescript ? 'TypeScript declaration' : 'description and JSON Schema'}`,
           'with describe_tools before calling it.',
+          ...(this.describeTopMatch ? ['When one match clearly leads, its declaration follows the results.'] : []),
           this.topLevelLine(),
         ].join(' '),
         inputSchema: {
@@ -967,8 +1133,14 @@ export class FlexToolCatalog<TScope = unknown> {
     return await this.core.onProposals(proposals, context as IFlexCatalogProposalContext);
   }
 
-  /** Search results or a namespace listing as text. */
-  public search(input: IFlexCatalogSearchInput = {}): string {
+  /**
+   * Search results or a namespace listing as text. A clear top match of a query's first page is
+   * followed by its declaration, as `describe` gives it with `options`.
+   */
+  public search(
+    input: IFlexCatalogSearchInput = {},
+    options: { declaredTypes?: Iterable<string>; maxBytes?: number } = {},
+  ): string {
     const limit = input.limit ?? limits.defaultSearchResults;
     const offset = input.offset ?? 0;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > limits.maxSearchResults) {
@@ -994,7 +1166,16 @@ export class FlexToolCatalog<TScope = unknown> {
       if (matches.length === 0) {
         return [`No methods match "${query}"${namespace ? ` in ${namespace}` : ''}.`, this.topLevelLine()].join('\n');
       }
-      return this.page(matches.map((entry) => `${entry.path} - ${entry.summary}`), offset, limit, 'matches');
+      const results = this.page(matches.map(({ entry }) => `${entry.path} - ${entry.summary}`), offset, limit, 'matches');
+      const [top, next] = matches;
+      const clear = offset === 0 && (!next || (top.named && top.score >= clearMatchMargin * next.score));
+      if (!this.describeTopMatch || !clear) return results;
+      // The declaration follows only while the whole answer fits what describe_tools may answer;
+      // an answer over the output limit would lose the results too.
+      const maxBytes = Math.min(options.maxBytes ?? limits.maxDescribeBytes, limits.maxDescribeBytes);
+      const declaration = this.describe({ methods: [top.entry.path] }, { ...options, maxBytes }).output;
+      const answer = `${results}\n\n${typeof declaration === 'string' ? declaration : JSON.stringify(declaration)}`;
+      return Buffer.byteLength(JSON.stringify(answer), 'utf8') <= maxBytes ? answer : results;
     }
     const node = tree.get(namespace)!;
     const lines = [...node.children.entries()].map(([child, count]) => `${child}.* (${count} method${count === 1 ? '' : 's'})`);
@@ -1022,8 +1203,11 @@ export class FlexToolCatalog<TScope = unknown> {
     const entries = requestedMethods.filter((path) => this.has(path)).sort(compareCodePoints)
       .map((path) => this.core.methods.get(path)!);
     const unknownMethods = requestedMethods.filter((path) => !this.has(path)).sort(compareCodePoints);
-    const knownTypes = requestedTypes.filter((name) => this.core.types.has(name)).sort(compareCodePoints);
-    const unknownTypes = requestedTypes.filter((name) => !this.core.types.has(name)).sort(compareCodePoints);
+    // A type is asked for by its identifier or by the name its schema gives it.
+    const identifierOf = (name: string): string | undefined =>
+      this.core.types.has(name) ? name : this.core.typeIdentifiers.get(name);
+    const knownTypes = [...new Set(requestedTypes.flatMap((name) => identifierOf(name) ?? []))].sort(compareCodePoints);
+    const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareCodePoints);
     const notes = [
       ...unknownMethods.map((path) => {
         const suggestions = closeMatches(path, this.methods);
@@ -1042,18 +1226,18 @@ export class FlexToolCatalog<TScope = unknown> {
       : this.describeTypescript(entries, knownTypes, notes, new Set(options.declaredTypes ?? []), maxBytes);
   }
 
-  /** The named types `describe_tools` results in `messages` declared. */
+  /** The named types the `describe_tools` and `search_tools` results in `messages` declared. */
   public declaredTypesIn(messages: readonly plugins.ModelMessage[] | undefined): Set<string> {
     const declared = new Set<string>();
     for (const message of messages ?? []) {
       if (message.role !== 'tool' || !Array.isArray(message.content)) continue;
       for (const part of message.content) {
-        if (part.type !== 'tool-result' || part.toolName !== toolNames.describe) continue;
+        if (part.type !== 'tool-result' || (part.toolName !== toolNames.describe && part.toolName !== toolNames.search)) continue;
         const output = part.output as { type?: string; value?: unknown };
-        if (output.type !== 'text' || typeof output.value !== 'string' || !output.value.startsWith(declaredTypesHeader)) continue;
-        const lineEnd = output.value.indexOf('\n');
-        const header = output.value.slice(declaredTypesHeader.length, lineEnd === -1 ? undefined : lineEnd);
-        for (const name of header.split(', ')) if (this.core.types.has(name)) declared.add(name);
+        if (output.type !== 'text' || typeof output.value !== 'string') continue;
+        for (const [, header] of output.value.matchAll(declaredTypesLine)) {
+          for (const name of header.split(', ')) if (this.core.types.has(name)) declared.add(name);
+        }
       }
     }
     return declared;
@@ -1196,10 +1380,24 @@ export class FlexToolCatalog<TScope = unknown> {
     const included: IMethodEntry[] = [];
     const omitted: string[] = [];
     const alreadyDeclared = new Set([...declared].filter((name) => !requestedTypes.includes(name)));
-    let types = this.core.typeClosure(requestedTypes, alreadyDeclared);
+    // Parameters' types are declared in full; a result's only `outputTypeDepth` levels deep.
+    const typesFor = (methods: IMethodEntry[]): string[] => {
+      const inputs = [...requestedTypes, ...methods.flatMap((entry) => this.core.methodTypes(entry).input)];
+      const outputs = methods.flatMap((entry) => this.core.methodTypes(entry).output);
+      return [...new Set([
+        ...this.core.typeClosure(inputs, alreadyDeclared),
+        ...this.core.typeLevels(outputs, this.outputTypeDepth, alreadyDeclared),
+      ])].sort(compareCodePoints);
+    };
+    let types = typesFor([]);
     const assemble = (methods: IMethodEntry[], typeNames: string[], skipped: string[]): string => {
-      const used = new Set(methods.flatMap((entry) => this.core.typeClosure(this.core.renderMethod(entry).types)));
-      const earlier = [...used].filter((name) => declared.has(name) && !typeNames.includes(name)).sort(compareCodePoints);
+      const shown = new Set(typeNames);
+      const named = new Set([
+        ...methods.flatMap((entry) => this.core.renderMethod(entry).types),
+        ...typeNames.flatMap((name) => this.core.renderType(name).types),
+      ]);
+      const earlier = [...named].filter((name) => declared.has(name) && !shown.has(name)).sort(compareCodePoints);
+      const undeclared = [...named].filter((name) => !declared.has(name) && !shown.has(name)).sort(compareCodePoints);
       const blocks: string[] = [];
       if (typeNames.length) blocks.push(`${declaredTypesHeader}${typeNames.join(', ')}`);
       for (const name of typeNames) blocks.push(this.core.renderType(name).text);
@@ -1212,6 +1410,7 @@ export class FlexToolCatalog<TScope = unknown> {
       }
       const trailing = [
         ...(earlier.length ? [`Declared earlier: ${earlier.join(', ')}; describe_tools({"types":[...]}) declares them again.`] : []),
+        ...(undeclared.length ? [`Not declared yet: ${undeclared.join(', ')}; describe_tools({"types":[...]}) declares them.`] : []),
         ...notes,
         ...(skipped.length ? [`Not included to stay within the size limit: ${skipped.join(', ')}; describe them in another call.`] : []),
       ];
@@ -1220,10 +1419,7 @@ export class FlexToolCatalog<TScope = unknown> {
     };
     for (const entry of entries) {
       const candidate = [...included, entry];
-      const candidateTypes = this.core.typeClosure(
-        [...requestedTypes, ...candidate.flatMap((method) => this.core.renderMethod(method).types)],
-        alreadyDeclared,
-      );
+      const candidateTypes = typesFor(candidate);
       const text = assemble(candidate, candidateTypes, entries.slice(candidate.length).map((method) => method.path));
       if (Buffer.byteLength(JSON.stringify(text), 'utf8') > maxBytes && included.length > 0) {
         omitted.push(...entries.slice(included.length).map((method) => method.path));
@@ -1248,7 +1444,7 @@ export class FlexToolCatalog<TScope = unknown> {
       const type = this.core.types.get(name)!;
       const schema = type.definition ?? type.schema?.json;
       return [{
-        name,
+        name: type.schemaName ?? name,
         ...(type.description ? { description: type.description } : {}),
         ...(schema === undefined ? { declaration: type.declaration! } : { schema: withoutDraft(schema) }),
       }];
@@ -1291,7 +1487,8 @@ export class FlexToolCatalog<TScope = unknown> {
       namedType: (ref) => {
         const match = definitionRefPattern.exec(ref);
         const key = match ? decodePointerToken(match[2]) : undefined;
-        return key && typeNamePattern.test(key) ? key : undefined;
+        if (key === undefined) return undefined;
+        return this.core.typeIdentifiers.get(key) ?? (typeNamePattern.test(key) ? key : undefined);
       },
       resolve: (ref) => {
         const target = resolvePointer(root, ref);