diff --git a/docs/architecture.md b/docs/architecture.md
index e35ee710cc..150f6acace 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -261,23 +261,31 @@ implements it **without modifying the loop**:
 
 ```ts
 import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
 
 export const name = 'my-tool'
 export const inject = ['tools']
 
 export function apply(ctx: Context) {
-  ctx.tools.register({
+  ctx.tools.register(defineTool({
     name: 'read_file',
     description: 'Read a file from disk.',
-    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
-    async execute(args: any) {
+    parameters: {
+      path: { type: 'string', required: true, description: 'Absolute file path' },
+    },
+    async execute(args) {
+      // args is typed: { path: string }
       const text = await readFile(args.path, 'utf8')
       return [{ type: 'text', text }]
     },
-  })
+  }))
 }
 ```
 
+(Raw JSON-Schema `ToolDefinition`s are still accepted by
+`ctx.tools.register()` directly — that's how MCP-sourced tools arrive.
+`defineTool` is the typed sugar for first-party tools.)
+
 ### A hook plugin (permission gate)
 
 ```ts
diff --git a/examples/echo-agent/README.md b/examples/echo-agent/README.md
index 03f11eecfb..5823d28b1d 100644
--- a/examples/echo-agent/README.md
+++ b/examples/echo-agent/README.md
@@ -18,8 +18,8 @@ Runnable demo: stdin chat with a scripted mock model and an echo tool.
 
 | File | Role | Key patterns demonstrated |
 |---|---|---|
-| `mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter([])`, streaming chunks with proper `block-start`/`block-end` protocol |
-| `echo-tool.ts` | Tool registration | `ctx.tools.register()`, tool execution returning `ContentBlock[]` |
+| `mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter(['mock-echo'], …)`, streaming chunks with proper `block-start`/`block-end` protocol |
+| `echo-tool.ts` | Tool registration | `ctx.tools.register(defineTool(…))` with typed `execute` args, tool execution returning `ContentBlock[]` |
 | `session-jsonl.ts` | Persistence | `session/event` listener + `session/flush` drain, fiber-dispose cleanup |
 | `stdio-chat.ts` | UI | `agent/stream-chunk`, `session/event` (tool/*), stdin→send/steer |
 | `start.ts` | Bootstrap | `Context` + `Loader` + `plugin-include` wired to `cordis.yml` |