ground-actions-to-registry

name	ground-actions-to-registry
description	Use when an agent will name a domain entity it does not control — a repo, channel, tool, agent, skill, model alias, team — and act on it; or when an agent reports an action on an entity that may not exist.

Ground Actions to Registry

Overview

Without a closed action vocabulary, an agent invents a tool/entity name from training memory, the call silently fails, and the agent self-reports success — producing a FALSE record with the real task undone. The fix is to make "what exists" an external, checkable list — never the model's memory.

When to use

• Any tool call with a name parameter (repo, channel, tool, agent, skill, model alias).
• Any fan-out whose prompts cite repos/tools/agents the model might confuse.
• An agent claims it acted on an entity you're not sure exists.

The technique

1. Typed tool registry + pre-execution name gate. An unknown tool name returns {"error":"ToolNotFound","valid":[...]} — never a silent fail. The model sees the valid options and self-corrects.
2. Domain-entity parameter gate. Resolve every name parameter against the live registry snapshot BEFORE execution; reject with {"error":"UnknownEntity","value":...,"valid_options":[...]}. (This cut tool-call hallucination 43%→0% in the cited deployment.)
3. Per-context scope manifest. Inject only the authorized registry subset into the prompt ("the model can't call what it can't see") + the rule: any name NOT in this manifest or returned by a tool this session must not be stated as fact.

Common mistakes

• Mandatory structured/JSON output WITHOUT a closed vocabulary — it makes identifier hallucination +10–15pp worse (slot-fill pressure). Add the vocab, not just a schema.
• A prompt instruction ("don't name X") instead of a tool-layer gate — too weak for small models, and naming the forbidden entity can even prime it.
• Letting the model declare success on a failed lookup.

Real-world impact

A local assistant agent repeatedly name-dropped a separate product's repo — nowhere in its own files — as "your codebase," a pure hallucination that a system-prompt repo-map did NOT suppress. The durable fix is a registry parameter-gate + a scope manifest (the actual live repos + tools), not a prompt; a deterministic rewrite-guard is only a stopgap.

Sources: arXiv 2605.11234 (ontology-grounded tool architecture); ranjankumar.in harness-engineering tool-registry.