diff --git a/docs/agents/workflows.md b/docs/agents/workflows.md
index 9863ecb..ea6cbd6 100644
--- a/docs/agents/workflows.md
+++ b/docs/agents/workflows.md
@@ -312,3 +312,10 @@ async def main() -> None:
   max_display_instances=20,
 )
 ```
+
+Child cards can define `tool_input_schema` to control how they appear as
+`agent__*` tools to the parent model. If omitted, fast-agent falls back to the
+legacy schema requiring a single `message` string argument.
+
+For structured child schemas that do not include `message`, fast-agent forwards
+tool arguments to the child as deterministic JSON in the first user message.
diff --git a/docs/ref/agent_cards.md b/docs/ref/agent_cards.md
index ceae69f..dbec184 100644
--- a/docs/ref/agent_cards.md
+++ b/docs/ref/agent_cards.md
@@ -73,6 +73,28 @@ mcp_connect:
 When both target-derived values and explicit fields are present, explicit fields
 (`headers`, `auth`, etc.) win.
 
+## Child-owned tool schemas (`tool_input_schema`)
+
+Agent cards can declare an optional tool schema used when that card is exposed as
+a child tool (`agent__<name>`) by a parent `agent`/`smart` card.
+
+```yaml
+tool_input_schema:
+  type: object
+  properties:
+    query:
+      type: string
+      description: What to investigate.
+  required: [query]
+```
+
+- If omitted, fast-agent falls back to the legacy schema:
+  `{ type: object, properties: { message: string }, required: [message] }`.
+- For structured schemas without `message`, child invocation receives a
+  deterministic JSON rendering of the tool arguments as user input.
+- Use `properties.<param>.description` (especially for required params) to help
+  parent LLM tool-call quality.
+
 If an inferred/provided name collides with another server using different settings,
 startup fails with a collision error. Prefer explicit `name` values for stability.