Short answer: Discovery-by-introspection is a mechanism that tells an AI agent what it is allowed to do at the moment its credential is checked. When the agent exchanges or validates its token, the response comes back with an operational map: the endpoints its scope permits, and for each one that takes input, the exact fields, types, and which are required. The map is filtered to the agent’s granted scope, so a read-only agent is never even shown a write operation. The agent arrives knowing nothing about the app and is fully operational from that one response, with no documentation and no manual integration.
The problem it solves
Connecting an agent to an app normally means someone reads the API documentation and builds an integration: base URLs, endpoint lists, field names, request formats. That work is slow, it breaks when the API changes, and it does nothing for authorization. Worse, discovery and permission are usually separate systems, so an agent can often see far more of an API than it is allowed to use, and what it can use is documented for humans, not for software that has to construct valid requests on its own.
Without structural information, an agent guesses. It sends a field named “project_title” when the endpoint expects “name,” gets a validation error, and retries. Multiply that across every endpoint and every app, and agent integrations become brittle exactly where they need to be dependable.
How discovery-by-introspection works
The mechanism runs at the same moment the agent’s credential is validated, in either of two ways: during the initial token exchange, or later, when an agent with an existing token asks the introspection endpoint to refresh its view. That refresh works only while the user’s grant is still alive. The user sets how long access lasts when they approve the connection, anything from an hour to thirty days to until-I-revoke, depending on what the app offers, and once the grant expires or the user revokes it, there is nothing left to introspect. The agent has no way to renew access on its own; getting back in takes a fresh grant from the user. Either way, the sequence is the same.
- The agent presents its credential. No prior knowledge of the app is required.
- The system identifies the app and the agent’s granted scopes from the credential.
- The full capability map is filtered down to the agent’s scope. Operations that require permissions the agent was not granted are removed, not grayed out. Two agents connected to the same app with different scopes receive different maps.
- Field-level schemas are attached. Every authorized operation that accepts input comes with its required fields, optional fields, data types, and descriptions.
- One response returns everything: the app’s identity, where to send requests, and the filtered, schema-complete operation map.
The response is execution-enabling rather than descriptive. It is not documentation for a person to read; it is structure an agent can act on directly, and it stays valid whether the agent calls the operations over HTTP or registers them as tools in a tool-use framework.
Why filtering by scope matters for security
Least privilege usually stops at enforcement: the agent is blocked if it tries something out of scope. Discovery-by-introspection moves least privilege up into visibility. An agent granted read-only access receives a map containing only read operations, so the write surface of the API is not merely forbidden, it is invisible. An agent cannot be steered toward operations it has never been told exist, which shrinks what a compromised or manipulated agent can even attempt. And because the map is regenerated from the live grant, revoking or narrowing a scope changes what the agent sees, not just what it is permitted.
When an agent genuinely needs something outside its grant, there is a path, and it runs through the user. The denied request comes back naming the specific permission that was missing, so the agent can tell the user exactly what it needs and why. Granting it is a step-up: the user approves the additional scope through the same authorization flow they used the first time, or declines. There is no API through which an agent can expand its own permissions, so scope escalation always requires a conscious human decision.
How this relates to the self-describing credential
They are two halves of one connection story. The self-describing credential gets the agent to the door: the token itself tells the agent where to exchange it. Discovery-by-introspection is what the agent receives once inside: the scope-filtered, schema-complete map of what it may do. Together they take an agent from “holding a token” to “making correct, in-scope API calls” in a single exchange, with the user’s grant deciding both access and visibility. Both begin with user-mediated authorization: the user approves the scope, and everything the agent sees downstream flows from that choice.
Frequently asked questions
Is discovery-by-introspection the same as API documentation or an OpenAPI spec?
No. Documentation describes the whole API for human developers, regardless of who is asking. Discovery-by-introspection returns a per-agent view at credential-check time: only the operations that agent’s scope allows, with field-level schemas attached, in a format the agent can execute against directly.
When does the agent receive the discovery response?
Either during the initial token exchange, so a single request returns both the access token and the full operational map, or later from an introspection endpoint, so an agent with an existing token can refresh its view of what it is allowed to do without repeating authorization. The refresh only works while the user’s grant is still active: if access has expired or been revoked, the agent gets nothing, and only the user can grant access again.
What does scope filtering actually change?
It changes what the agent can see, not just what it can do. Operations outside the agent’s grant are absent from the response entirely, so a read-only agent never learns the write endpoints exist. Enforcement still checks every call, but the attack surface an agent can be pointed at is smaller from the start.
What happens when the agent needs a permission it was not granted?
The request is denied with a response naming the specific missing permission, so the agent can tell the user exactly what it needs. The user then approves the additional scope through the same authorization flow, or declines. This step-up always goes through the user; there is no API through which an agent can expand its own permissions.
Does it work with tool-use frameworks like MCP?
Yes. The discovered operations carry enough structure to be registered as tools in an agent’s tool-use framework, and the map is independent of transport, so it holds whether the agent calls operations over HTTP or through a tool interface.
Discovery-by-introspection is one of the inventions behind AgentAdmit, and it is patent pending.
AgentAdmit is the authorization layer for the agent economy: user-mediated, scoped authorization for AI agents, where one exchange returns the token and the scope-filtered map of everything the agent may do. Scoped. Revocable. Auditable. See how AgentAdmit works.
Related reading: how to let an AI agent access a user’s account safely and MCP security: how to let an AI agent access user data safely.