{
  "id": 10155787,
  "title": "Undocumented handlers don't exist to the agent",
  "url": "https://urgent.news/2026/09/27/undocumented-handlers-dont-exist-to-the-agent",
  "topic": "ai",
  "section": "AI",
  "published": "2026-09-27T06:10:00.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/marc_kumiko/undocumented-handlers-dont-exist-to-the-agent-e71"
  },
  "original_language": "en",
  "account": "An AI agent was integrated into a product with a full write/query surface, but it encountered issues. The agent had permission to call writes, yet half the handlers it required simply did not appear in its tool list. The handlers were present, but the missing element was a description string. The AI agent receives a manifest built from each feature the app mounts, such as handlers, screens, and entities. Each entry requires a short description, which, if absent, causes the entry to be dropped. As a result, the agent never learns the existence of the handler. Initially, this was treated as documentation polish, but it proved to be a gatekeeper for the agent. Out of 21 handlers across the AI pipeline and prompt store features, 21 were in this state. The agent could access the UI, but it couldn't interact with handlers lacking descriptions. Additionally, writes and queries default to different risk levels, with the UI offering an \"always allow\" option. However, two writes were marked as \"high risk,\" meaning an always allow was impossible. The code does not allow changing the default risk level for high-risk writes. The team implemented gap tests to ensure agent-visible features have descriptions and set risk levels accordingly. These tests fail if a handler lacks a description, preventing the agent from recognizing its existence. The team now emphasizes that if a human can click a feature and an agent should be able to call it, a description must be written alongside the handler definition.",
  "summary": "We wired an in-app AI agent into a product that already had a full write/query surface. Auth was fine. The agent had permission to call writes. Half the handlers it needed simply never showed up in its tool list. The agent said it couldn't find them. The handlers existed. What was missing was a description string. What the agent can see Our agent doesn't get raw TypeScript. It gets a manifest…",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}