# Ground Actions To Registry

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

- Skill: `oimiragieo/ground-actions-to-registry` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/ground-actions-to-registry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/ground-actions-to-registry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/ground-actions-to-registry

---


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