A Dynamic Capability Registry Keeps HarmonyOS Agents From Guessing What Tools Exist
Agent systems break when the model invents tool names or the client hardcodes assumptions about what the server can do. A registry that both the model and the client read from a single source of truth eliminates that class of failure and turns capability changes into a one-place config update.
When an AI agent page connects to a real app, the client needs to know which capabilities are available, what parameters they require, and how risky they are. Hardcoding buttons forces a client rebuild every time a tool changes. A capability registry served from a local Gateway solves this by listing every tool with its description, input schema, risk level, confirmation requirement, and return example.
The HarmonyOS client fetches `/tools` at runtime and renders a capability console that shows total tools, directly executable count, and confirmation-required count. Low-risk tools like `time_now` and `local_status` can run immediately; medium-risk tools like `http_check` appear locked. The Gateway enforces a strict whitelist—calling an unregistered tool returns `TOOL_NOT_FOUND` with no fuzzy matching—and validates parameters server-side against each tool's schema. The client adds its own conservative whitelist on top, unlocking only the two tools it has verified, even if the registry marks others as low risk.
Execution results stay in a single panel with a traceable requestId, and all UI counts and filter states derive from the registry data rather than hardcoded constants. Adding or modifying a capability becomes a configuration change on the Gateway, not an ArkTS code change.
A capability registry shifts the integration model from 'client knows the server's API surface' to 'client discovers the server's API surface,' which is the same architectural leap that made REST discoverable via hypermedia.
Placing parameter validation only on the client is a security boundary error; the Gateway must enforce schemas because any request that reaches it could have bypassed the UI.
The client's extra whitelist is a practical admission that risk labels from a server are advisory, not authoritative—trust but verify, and ship conservatively.
Returning `TOOL_NOT_FOUND` instead of letting the model guess closes a common agent vulnerability where hallucinated tool names become runtime errors or worse.