API Discovery Service
Google recently released gws, a command line interface (CLI) for all of Google Workspace. They are describing it as
One CLI for all of Google Workspace — built for humans and AI agents
gws doesn’t ship a static list of commands, instead it reads Google’s own API Discovery Service at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, gws picks it up automatically.
We want to talk about that API Discovery Service in this post.
Google API Discovery Service
Google first presented the Google API Discovery Service way back in Google I/O 2011! They described it as a service that exposes metadata about Google APIs in a machine-readable format called “Discovery Document” for client libraries and other tools to consume.
Google Discovery Document (GDD)
Google Discovery Document is a machine-readable document for each Google API. Each document contains a list of API methods and available parameters for each method, a list of available OAuth 2.0 scopes, and inline documentation of methods, parameters, and available parameter values.
API definition/ description
At the time Google was working on the API Discovery Service, OpenAPI was not born yet and Swagger 1 was not as ubiquitous and popular. Fast forward now, there are more popular API definition/ description languages available. Depending on the maturity of the organization, one may find APIs defined using one of these: OpenAPI specification (OAS), AsyncAPI specification, Web Services Description Language (WSDL), JSON RPC, Google Discovery Document, Protocol Buffers, etc.
A modern API Discovery Service would need to support APIs defined using one or more such languages.
Consuming APIs
To understand the importance of the API Discovery Service, let’s first understand how APIs have been consumed and would be consumed.
Developer Portal
Typically, API producers would make API documentation available on a Developer Portal. Content on developer portal is organized for human developers building business process integrations. Modern developer portals generate API references automatically from machine-readable API definitions. Developer portal is also used for documenting APIs that do not have machine-readable API definitions.
Developing integrations conventionally
Application developers would read API related content from the developer portal, use provided SDK (like gws) or download API definition if available and generate client-side code from the definition using tools available and code the integration in their applications.
Developing integrations using AI code assistants
Cisco recently released an MCP (Model Context Protocol) server for its DevNet (developer portal) content. This MCP server enables IDE AI assistants (Github Co-pilot, Cursor, Claude Code, JetBrains AI, etc.) to call tools searching Cisco’s API documentation. This enables software developers to have more accurate, official and most current context regarding Cisco APIs without switching windows.
Cisco advises that output from any AI assistant using their MCP server can be incomplete, incorrect, or insecure and advises to treat the generated code the way you would, a draft from a junior colleague: review it, test it, and approve it before running it in any real environment.
Integrations with Agentic AI
Agentic AI refers to AI systems that don’t just respond to a single prompt, but autonomously pursue goals across multiple steps — planning, taking actions, observing results, and adapting until the task is complete. Here, the system decides what to do next rather than waiting for a human to direct every step.
Most agentic systems run a continuous cycle:
Think → Act → Observe → Think → Act → …
This is sometimes called a ReAct loop (Reasoning + Acting). The agent reasons about what to do, does it, sees what happened, and reasons again — until the goal is met or it gives up.
Here is an example of an agentic behavior — notice no human directed API calls.
- The agent (Claude/OpenClaw) receives a goal — “investigate alert abc-123”
- It selects the right skill or MCP tool
- Executes a sequence of API calls either directly using skills with CLI, script or indirectly using MCP tools wrapping one or more APIs
- Observes each response and passes outputs into the next step
- Produces a final synthesized report
Multiple approaches for calling an API
- The agent decides at runtime whether to load a skill or call an MCP tool
- A skill is lazy-loaded markdown — the agent reads it and directly executes what it describes (CLI commands or scripts)
- An MCP tool is a function the agent calls via the MCP protocol — the MCP server handles actual execution
- Both paths ultimately reach the external API, but via different execution models — local shell vs remote process
Agentic AI Workflows Using Google Workspace APIs
Now that we know how agentic AI workflows work, following diagram shows how an agent would use gws CLI or MCP tools to call Google Workspace APIs with the help of Google’s API Discovery Service.
- Path A — CLI: agent runs
gwsgmail +triage directly as a shell command — no MCP server needed, agent’s native terminal access is enough - Path B — MCP: agent calls
gwsmcp as a stdio MCP server, exposing all Workspace tools via the MCP protocol for the agent
Each process fetches the Google Workspace API schemas independently from the Google API Discovery Service when it starts up, before handling any requests. For both paths, gws queries at startup to build its command surface dynamically — so new Workspace API endpoints appear automatically without any CLI update.
Are you ready for Agentic AI?
Isn’t it wonderful to know that Google can still use its API Discovery Service that was designed and developed fifteen years ago for a new CLI (gws) that is built for humans and AI agents? It keeps giving them good return on investment. Kudos to them!
If you have invested in exposing your business capabilities as APIs while digitally transforming your organization, you have already formed a backbone for Agentic AI driven business processes. Making your APIs easily discoverable to rapidly evolving agentic AI ecosystem of agents, frameworks, platforms, etc. is only going to increase return on your investment in APIs.
Question to CIOs and their leadership teams
Do you have something like Google’s API Discovery Service in-house?
If the answer is no or you want to know more about channelseal, let’s talk.
-
The Swagger API project was created in 2011 by Tony Tam, technical co-founder of the dictionary site Wordnik. In 2015, the Swagger project was acquired by SmartBear Software. The Swagger Specification was donated to the Linux Foundation and renamed the OpenAPI. Once that happened, OpenAPI acceptance accelerated. ↩