diff --git a/docs/guides/configuring-models-rules-tools.mdx b/docs/guides/configuring-models-rules-tools.mdx
index 2a2d3d87e85..b31e6e938be 100644
--- a/docs/guides/configuring-models-rules-tools.mdx
+++ b/docs/guides/configuring-models-rules-tools.mdx
@@ -107,6 +107,19 @@ When configuring a local model or MCP server, you can use the same mustache nota
 </Card>
 </Columns>
 
+<Info>
+**When to use `secrets.` vs `inputs.`**
+
+For most use cases, **use `${{ secrets.SECRET_NAME }}`** directly in your configuration. This is the recommended approach for both personal and organizational workflows.
+
+Use `${{ inputs.INPUT_NAME }}` only when you need flexibility to:
+- Allow users to customize which secret a block uses without editing the block itself
+- Change the secret name without modifying the block configuration
+- Create reusable blocks where different users may have differently-named secrets
+
+This pattern is inspired by GitHub Actions, where inputs provide an abstraction layer between block definitions and user-specific values. For most scenarios, directly referencing `secrets.` keeps configuration simpler and more straightforward.
+</Info>
+
 ## Overriding Properties
 
 You can directly override properties using the `override` syntax:
diff --git a/docs/hub/blocks/create-a-block.mdx b/docs/hub/blocks/create-a-block.mdx
index 3b59267a8b2..af3199ab906 100644
--- a/docs/hub/blocks/create-a-block.mdx
+++ b/docs/hub/blocks/create-a-block.mdx
@@ -27,3 +27,13 @@ After filling out information on the block, you will want to create a block foll
 ### Block Inputs
 
 Blocks can receive values, including secrets, as inputs through templating. For values that the user of the block needs to set, you can use template variables (e.g. `${{ inputs.API_KEY}}`). Then, the user can set `API_KEY: ${{ secrets.MY_API_KEY }}` in the `with` clause of their agent.
+
+<Info>
+**Choosing between `secrets.` and `inputs.`**
+
+When creating blocks for the hub:
+- Use `${{ inputs.INPUT_NAME }}` in your block definition when you want users to be able to customize which secret is used
+- Users will then map their own secrets using `${{ secrets.SECRET_NAME }}` in the `with` clause
+
+For personal or single-use configurations, you can skip the inputs layer and reference `${{ secrets.SECRET_NAME }}` directly in your block.
+</Info>