docs: include JSDoc in website API markers

website/zh-CN/api/harness/tools.md

@@ -11,6 +11,12 @@ Tool registry and execution pipeline. Scoped registrations shadow globals; one v
 ### ctx.tools.register(definition)
 
 ```ts website-api
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - the tool schema, execution, and optional presentation functions.
+ * @returns the exact disposer that unregisters the tool.
+ */
 register(definition: ToolDefinition): () => void
 ```
 
@@ -25,6 +31,13 @@ Register globally or in the calling agent scope. Scoped tools shadow globals; du
 ### ctx.tools.restrict(filter)
 
 ```ts website-api
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
 restrict(filter: ToolRestriction): () => void
 ```
 
@@ -39,6 +52,16 @@ Restrict global tools for the calling agent scope. Empty filters, unknown names,
 ### ctx.tools.guard(guard)
 
 ```ts website-api
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
 guard(guard: ToolGuard): () => void
 ```
 
@@ -53,6 +76,15 @@ Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A
 ### ctx.tools.get(name, scope?)
 
 ```ts website-api
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
 get(name: string, scope?: ScopeKey): ToolDefinition | undefined
 ```
 
@@ -68,6 +100,12 @@ Look up a tool as one scope sees it (scoped shadows global; a restricted-away gl
 ### ctx.tools.schemas(scope?)
 
 ```ts website-api
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
 schemas(scope?: ScopeKey): ToolSchema[]
 ```
 
@@ -82,6 +120,13 @@ Project visible definitions onto the allowlisted model-facing schema fields, exc
 ### ctx.tools.executionMode(exec)
 
 ```ts website-api
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
 executionMode(exec: ToolExecutionInput): ToolExecutionMode
 ```
 
@@ -96,6 +141,15 @@ Classify a pending call through the caller's visible tool definition. Only an ex
 ### ctx.tools.execute(exec)
 
 ```ts website-api
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy, and final
+ * notification. Tool and listener failures resolve as materialized error
+ * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is
+ * the same lossless, frozen snapshot final observers receive.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 ```