I am looking at Registries and Metadata as a possible solution to my needs, but so far I probably lack a little bit of imagination on how to structure it the best.

For those who work with structured data and LLMs know that you need to provide additional description in .meta which will be passed as description of jsonschema to underlying models when using ai-sdk or when doing .toJSONSchema

The problem is that we have many such calls that often operate on the same schema with some modifications, so the schema often gets extended or description of base schema's fields need to be updated to provide different instructions for this new call.

For example the initial call might be "Find me all Suppliers in London that would fit this event I am planning" and the supplier schema might look like this

const supplierSchema = z.object({
  name: z.string().meta({ description: 'The name of the supplier' }),
  description: z
    .string()
    .meta({ description: 'Short description of the supplier. Max 500 characters' }),
})

Then the next call might be to a tool that enriches the supplier
"Enrich supplier with provided tools"

const enrichedSupplierSchema = supplierSchema.extend({
  services: z.array(servicesSchema).meta({description: 'Find supplier services using available tools'}),
  sources: z
    .array(
      generatedSupplierSourceSchema.meta({
        description:
          'If Google Places API Tool was used or google places id is known for this supplier, specify it as a source here',
      }),
    )
    .default([])
    .meta({
      description:
        'When using any tools that sources additional supplier details from external API, provide the source details',
    }),
})
}) 

Now for example if we have LLM call that does repeated search and then merging/deduplication like

Compare previously discovered supplier provided in the input below with this newly discovered supplier. If this is the same supplier, identify updated fields and return merged supplier object

Now I have to provide a schema again, but extending enrichedSupplierSchema can be confusing to LLM because the description of some fields mentions an action Find... which can lead to hallucinations easily.

This problem multiplies of course when the schema is much bigger and includes some other nested schemas. It's very easy to lose track of what extends what and what metadata descriptions it carries.

My idea is that I can define a base schema with no meta descriptions. Then have a sharedSupplierSchemaRegistry where I can add the base descriptions that don't usually change per call and just describe type of information and type of data expected in field.

Then a searchSupplierSchemaRegistry can have some search specific only fields that sometimes require some more actionable descriptions. And then searchSupplierSchema can potentially use a mix of base registry and search registry schemas etc.

What's not clear is what are the good patterns of creating this, so far the docs only show a basic registries with a single schemas. Also not clear if I can use the value returned by myRegistry.get when adding a schema to a different registry?

z.object({
   name: z.string().register(registry2, registry1.get(baseNameSchema)),
})

Like would this work for example? (I know I know I should just try, but for now I'm just toying around with the idea and gathering some info)

Additionally can a registry schema be z.object({}) that itself references metas either from other registries or with inline meta?

i.e. can I do this?

const myRegistry1(...)
const myRegistry2(...)

const emailSchema = z.email().meta({ 
  description: "Business email address of supplier",
});

const nameSchema = z.string().meta({description: 'Name of supplier'})
myRegistry1.add(nameSchema, {description: 'Some other description for the same schema but in a different registry?'})

const myObjectSchema = z.object({
  name: nameSchema,
  email: emailSchem,
})

// Are whole objects with nested schemas allowed and what will happen when the object has nested schemas linked to other registries?
const myRegistry2.add(myObjectSchema, {//??})

And can I even add an object schema to registry and provide meta for nested fields? I am guessing not and description will only be added to the object definition itself right?

Would appreciate any thoughts or maybe there are some established patterns already