# Agent tools and WebMCP With discovery enabled for a Site, the SDK proposes agent tools from the structure of your application's own same-origin JSON requests. A workspace owner reviews each proposed action or workflow and enables it. Enabled tools are offered to agents in the page through WebMCP where the browser supports it, and through the SDK's in-page runner everywhere else. ## Safety rules that always apply - Discovered tools are disabled until reviewed. Approval is rechecked before every call, and schema drift disables a tool and its workflows until someone reviews the change. Enabling a tool also lints its inputSchema as JSON Schema 2020-12 (object root, known keywords, no $ref, satisfiable constraints); a tool whose stored schema fails the lint is refused and is never listed or executable. The docs MCP server validates tools/call arguments against the same kind of schema, and its errors name keywords and locations, never values. - Write operations ask the person at the page for confirmation. - Tool calls are ordinary same-origin requests from the signed-in page, so your backend's own authentication and authorization decide every one of them. A tool never bypasses them. - Discovery records shapes only (methods, path shapes, field names and types), never typed values, cookies, credentials or request bodies. - A path input fills only an identifier slot (digits, UUID, ULID, hex, opaque token, date, version or @handle). Before every call the runner checks that the filled-in path templates back to exactly the reviewed path, with each value in its reviewed format, and is not a sensitive route, so an input such as `export`, `new` or `password-reset` can never reach a sibling route nobody reviewed. Requests whose path holds free text (a search phrase or a person's name) are never proposed as tools; tools stored that way by an earlier version are disabled on upgrade and need review. - Consent withdrawal cancels running tool work and removes registered tools. Tool results are announced with untrustedContentHint: they come from your API and agents should treat them as data. ## Names, descriptions and update grades Discovery can link a request to the control that caused it, so proposed tools get readable names and descriptions: - **Trigger.** When a same-origin request starts within a second of a trusted click on a button, link, menu item, option or tab, the action records the control's role. A request first seen without a click (page load, background refresh, badges, consent banners) is never linked on that page, and any later interaction (another click, a change in a select or text field) replaces the earlier one. Enter-key submissions use the form's default button. Links to `blob:` or `data:` URLs link nothing. - **Label text and privacy.** The control's accessible name is computed in the page (aria-labelledby, aria-label, visible text without hidden or aria-hidden parts, then title). Text is never read from inputs, selects, textareas or editable regions, or from anything inside `data-telltale-ignore`, and no label is taken on a sensitive page. Digits, email addresses, URLs, domains and @handles are removed and the text is capped at 60 characters. The text leaves the page in clear only when you opt in by putting `data-telltale-label` on the control or an ancestor (a value is used as the label; an empty attribute allows the computed text). Otherwise the page sends only an HMAC-SHA256 token of the text, and by default that is all Telltale ever uses: the token never names anything and the text is never requested. **Token reveal** is a per-Site opt-in, off by default (POST /api/admin/label-reveal-setting {siteId, enabled}, owners and admins; the Site record shows labelReveal, and /api/sdk/init returns it as labelReveal so pages compute tokens only while it is on). With it on, Telltale counts the distinct sessions that send each token and asks for the text only after at least five sessions sent the same one (the server setting `TELLTALE_LABEL_MIN_SESSIONS` changes the threshold, minimum 2); only then does a page that still holds the text send it, and Telltale keeps it only if it reproduces the token. Know what this guard is before you turn it on: - The threshold counts SDK sessions, not people. One person who signs out and in, or whose page calls `reset()`, is several sessions, so a person's own name on a button can reach the threshold alone. - Tokens are pseudonymous, not secret. The key is derived from your publishable key, which is in your page, so anyone who sees the traffic (Telltale included) can test guesses offline, and short labels such as names are easy to guess. - So a row's customer content (a report name, a person's name) should never be part of a control's name. Mark such controls with `data-telltale-label="Export report"` (or `data-telltale-ignore`) instead. Turning reveal off again stops every request and stops earlier revealed texts from naming anything. - **Field descriptions.** For a field submitted from a form (or bound with `data-telltale-field`), the description comes from `toolparamdescription` on the control, then its `