# 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#L438) ### 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#L538) ### 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#L578) ### 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#L629) ### 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#L731) ### 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#L741) ### ctx.tools.executionMode(exec) ```ts website-api executionMode(exec: ToolExecutionInput): ToolExecutionMode ``` 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. - `exec` — call name, parsed arguments, and optional agent scope. **Returns** the fail-closed scheduling mode. [Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/tools/src/index.ts#L762) ### ctx.tools.execute(exec) ```ts website-api async execute(exec: ToolExecutionInput): Promise ``` 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#L782)