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

<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->

# ctx.tools

`ToolRegistry` — provided by `@deepseek-ai/dsh-tools`.

Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L378)

### ctx.tools.register(definition)

```ts website-api
register(definition: ToolDefinition): () => void
```

Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.

- `definition` — the tool schema, execution, and optional presentation functions.

**Returns** the exact disposer that unregisters the tool.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L468)

### ctx.tools.restrict(filter)

```ts website-api
restrict(filter: ToolRestriction): () => void
```

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.

- `filter` — global-surface mask: `allow` (keep only) and/or `deny` (remove).

**Returns** the exact disposer that lifts this restriction.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L508)

### ctx.tools.guard(guard)

```ts website-api
guard(guard: ToolGuard): () => void
```

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.

- `guard` — synchronous check; a returned string denies the execution.

**Returns** the exact disposer that unregisters the guard.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L559)

### ctx.tools.get(name, scope?)

```ts website-api
get(name: string, scope?: ScopeKey): ToolDefinition | undefined
```

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.

- `name` — the tool name as registered.
- `scope` — the viewing scope (the agent); omitted = the global view.

**Returns** the definition the scope resolves, or undefined when none is visible.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L661)

### ctx.tools.schemas(scope?)

```ts website-api
schemas(scope?: ScopeKey): ToolSchema[]
```

Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.

- `scope` — the viewing scope (the agent); omitted = the global view.

**Returns** one deep-cloned schema per visible tool.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L671)

### ctx.tools.execute(exec)

```ts website-api
async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
```

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.

- `exec` — the typed same-process call input. The registry assigns its correlation token before policy begins.

**Returns** the materialized final result.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L694)