← Back to concept explainers

Concept Fable

Tool registry

Conclusion first:A tool registry is a centralized catalog and control layer for the tools available to an Agent. It records tool names, purposes, parameter schemas, invocation methods, permission requirements, risk levels, approval rules, rate limits, return formats, and owners. For enterprise Agents, a tool registry is not a simple list, but infrastructure that lets the model use external capabilities safely, controllably, and audibly.

Tool Registry · AI agent platform

Read the story first. There is no rush to give a definition here; let the question grow on its own first.

Fable

The tool room in the castle that had no checklist

In Black Pine Castle there was a very large tool room. It held hammers, ropes, keys, torches, ledger seals, carriage tokens, and a few strange instruments whose purpose only the old steward knew. In the past, when the castle had few people, anyone who needed a tool just took it. They put it back when done, and things mostly worked out.

Later the castle became busy. The kitchen needed the chimney repaired, the stables needed a new door bolt, the accounting office needed a seal stamped, the guards needed torches. Everyone said they were just taking a small tool, but the tool room grew messier and messier. Someone took the warehouse key and forgot to log it, someone used the accounting seal on a document that should not have been stamped, someone took the roof-repair rope to tie down a cart, and the next day the craftsman discovered the rope was gone when he went up to the roof.

The castellan initially thought the problem was that people did not follow the rules, so he posted a notice: please return tools after use. The notice was beautifully written, but it did not help much. The real problem was not returning tools, but that no one knew which tools could be used by whom, which tools were dangerous, which tools required two people to confirm together, and which tools were already broken.

One day, a newly arrived apprentice was ordered to repair a well. He walked into the tool room and saw a silver key with no label. He thought it was the well cover key, but it opened the cellar door. The cellar stored winter grain, and with the door open all night, moisture got in and half the wheat was ruined. The apprentice meant no harm; he simply saw a usable tool.

The old steward did not punish the apprentice. He called everyone to the door of the tool room and said: a tool room without a checklist is not a tool room, it is a trap. The more tools there are, the less you can rely only on memory and good intentions.

Over the next seven days, he did not add new locks, but made a thick tool manual. Each tool had a name, purpose, storage location, who could use it, whether approval was required before use, what records had to be left after use, and what losses misuse could cause. Next to the torch was written fire risk; next to the accountant's seal was written that two people must confirm; next to the warehouse key was written that it could only be collected during the day; the broken pulley was marked as disabled.

At first everyone found the tool catalog a nuisance. Later they discovered that the catalog was not meant to stop people from working, but to let the right people get the right tools faster and to keep dangerous tools from being taken by mistake. New apprentices no longer had to guess, and old craftsmen no longer had to explain every day.

More importantly, the castle lord finally dared to hand some tools to the newly arrived automatic puppets for odd jobs. Because the puppets could not casually reach into the tool room, they could only apply according to the tool register: which tool was needed, what it was for, which parameters it carried, and what the risk level was. If the tool register did not agree, they could not get it. Black Pine Castle later had more tools, but it became quieter instead. Not because there were fewer tools, but because before each tool was used for the first time, it had already been named, registered, graded, authorized, and placed into an order the castle could understand.

Reveal

This story is about: tool registry

A tool registry is a centralized catalog and control layer for the tools available to an Agent. It records tool names, purposes, parameter schemas, invocation methods, permission requirements, risk levels, approval rules, rate limits, return formats, and owners. For enterprise Agents, a tool registry is not a simple list, but infrastructure that lets the model use external capabilities safely, controllably, and audibly.

What matters is that it is not just a term, but a structural problem that repeatedly appears in real AI / Agent systems. Understanding it lets you judge when to add a model, when to change a process, and when to add governance.

Metaphor mapping

  • Tool room: the set of tools inside an enterprise that can be invoked by an Agent, including APIs, databases, system operations, files, message sending, and more
  • The unlabeled silver key: a tool exposed to the Agent but lacking description, permissions and risk boundaries
  • The apprentice mistakenly opened the cellar: the model or agent chose the wrong tool, causing unintended business consequences
  • Notice "Please return after use": relying only on principled reminders or verbal rules cannot govern the use of complex tools
  • Tool Catalog: A Tool Registry That Centrally Describes Tool Capabilities, Parameters, Permissions, Risks, and Approval Requirements
  • Different rules for torches, seals and warehouse keys: different tools require different permissions, audits and human confirmation
  • Automatic puppets apply through the tool registry: at runtime, the Agent decides based on the registry whether a tool is visible, available, and executable
  • More tools, yet quieter: once tool governance matures, capability expansion no longer adds chaos and risk linearly

Andy Ren Xu's judgment

The practical value of this concept is that it helps you break "AI features that look smart" into deliverable, verifiable, and governable units of work.

Tool callingfunction schemapermissionsagent runtimeAPI catalogMCP

Related distinctions

This concept is easily confused with adjacent concepts; it is recommended to continue to the comparison page.

京ICP备2026014272号