diff --git a/fern/apis/fai/definition/document.yml b/fern/apis/fai/definition/document.yml
index 300653acd..d9ecf9f4e 100644
--- a/fern/apis/fai/definition/document.yml
+++ b/fern/apis/fai/definition/document.yml
@@ -22,28 +22,32 @@ service:
           properties:
             document:
               type: string
-              docs: The content of the document that will be returned in the tool response
+              docs: The content of the document that will be returned to Ask Fern during document retrieval.
             chunk:
               type: optional<string>
-              docs: The chunk of the document that will be indexed as a vector. If not provided, the document will be indexed.
+              docs: The textual content that should be vectorized when indexing the document. If not provided, the full document will be vectorized.
             title:
               type: optional<string>
-              docs: The title of the document
+              docs: The title of the document. This will be used with the `url` when Ask Fern cites this document.
             url:
               type: optional<string>
-              docs: The url of the document
+              docs: The url of the document. This will be used as the source of the document when Ask Fern cites it.
             version:
               type: optional<string>
-              docs: The version of the document
+              docs: |
+                The version of the document. This will be compared against when running Ask Fern with version filters.
+                If null, the document will be retrievable by all versions.
             product:
               type: optional<string>
-              docs: The product of the document
+              docs: |
+                The product of the document. This will be used to filter documents when running Ask Fern with product filters.
+                If null, the document will be retrievable by all products.
             keywords:
               type: optional<list<string>>
-              docs: The keywords of the document
+              docs: The keywords of the document. Adding keywords can improve document matching.
             authed:
               type: optional<boolean>
-              docs: Whether the document is authed
+              docs: Whether the document is authed. If true, the document will be retrievable by all users.
       response: DocumentIdResponse
       errors:
         - commons.BadRequestError
@@ -64,28 +68,38 @@ service:
           properties:
             document:
               type: optional<string>
-              docs: The content of the document that will be returned in the tool response.
+              docs: |
+                The updated content of the document that will be returned to Ask Fern during document retrieval.
+                If not provided, this field will remain unchanged.
             chunk:
               type: optional<string>
-              docs: The chunk of the document that will be indexed as a vector.
+              docs: |
+                The updated textual content that should be vectorized when indexing the document.
+                If not provided, this field will remain unchanged.
             title:
               type: optional<string>
-              docs: The title of the document
+              docs: |
+                The updated title of the document. If not provided, this field will remain unchanged.
             url:
               type: optional<string>
-              docs: The url of the document
+              docs: |
+                The updated url of the document. If not provided, this field will remain unchanged.
             version:
               type: optional<string>
-              docs: The version of the document
+              docs: |
+                The updated version of the document. If not provided, this field will remain unchanged.
             product:
               type: optional<string>
-              docs: The product of the document
+              docs: |
+                The updated product of the document. If not provided, this field will remain unchanged.
             keywords:
               type: optional<list<string>>
-              docs: The keywords of the document
+              docs: |
+                The updated keywords of the document. If not provided, this field will remain unchanged.
             authed:
               type: optional<boolean>
-              docs: Whether the document is authed
+              docs: |
+                The updated authed status of the document. If not provided, this field will remain unchanged.
       response: Document
       errors:
         - commons.BadRequestError
diff --git a/fern/apis/fai/definition/guidance.yml b/fern/apis/fai/definition/guidance.yml
index 9f4af5143..fd4dff991 100644
--- a/fern/apis/fai/definition/guidance.yml
+++ b/fern/apis/fai/definition/guidance.yml
@@ -8,8 +8,7 @@ service:
   base-path: /guidance
   endpoints:
     createGuidance:
-      docs: |
-        Create a guidance for a given domain. Guidance can be used to provide additional context to Ask Fern and improve its accuracy.
+      docs: Index a guidance document for a given domain
       path: /{domain}/create
       method: POST
       audiences:
@@ -22,10 +21,12 @@ service:
           properties:
             context:
               type: list<string>
-              docs: The context of the guidance document, as a list of strings, that will be indexed.
+              docs: |
+                The context of the guidance document, as a list of strings, that will be indexed.
+                Each string will be vectorized separately to generate a separate record.
             document:
               type: string
-              docs: The content of the guidance document that will be returned in the tool response
+              docs: The content of the guidance document that will be returned to Ask Fern during Ask Fern retrieval.
       response: GuidanceIdResponse
       errors:
         - commons.BadRequestError
@@ -45,11 +46,15 @@ service:
         body:
           properties:
             context:
-              type: list<string>
-              docs: The context of the document, as a list of strings, that will be indexed.
+              type: optional<list<string>>
+              docs: |
+                The updated context of the guidance document, as a list of strings, that will be indexed.
+                If not provided, this field will remain unchanged.
             document:
-              type: string
-              docs: The content of the document that will be returned in the tool response. If not provided, the document will be removed from the index.
+              type: optional<string>
+              docs: |
+                The updated content of the guidance document that will be returned to Ask Fern during Ask Fern retrieval.
+                If not provided, this field will remain unchanged.
       response: Guidance
       errors:
         - commons.BadRequestError