| 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
- 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.
- 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.)
- 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.
