diff --git a/.changeset/clarify-invoke-metadata-docs.md b/.changeset/clarify-invoke-metadata-docs.md
new file mode 100644
index 000000000..73f26d906
--- /dev/null
+++ b/.changeset/clarify-invoke-metadata-docs.md
@@ -0,0 +1,5 @@
+---
+"braintrust": patch
+---
+
+docs(functions): clarify where invoke metadata reaches code functions
diff --git a/js/src/functions/invoke.ts b/js/src/functions/invoke.ts
index f7bbb35f5..5a5ada01b 100644
--- a/js/src/functions/invoke.ts
+++ b/js/src/functions/invoke.ts
@@ -78,8 +78,10 @@ export interface InvokeFunctionArgs<
 
   /**
    * Additional metadata to add to the span. This will be logged as the `metadata` field in the span.
-   * It will also be available as the {{metadata}} field in the prompt and as the `metadata` argument
-   * to the function.
+   * It will also be available as the {{metadata}} field in the prompt. For code functions, it is passed
+   * through the hooks (the handler's second argument in TypeScript, `hooks.metadata` in Python), not
+   * as the handler's `metadata` argument, which is read from `input`. To fill the handler's `metadata`
+   * argument, nest it in `input`, e.g. `invoke({ ..., input: { input: ..., metadata: { ... } } })`.
    */
   metadata?: Record<string, unknown>;
   /**