TypeSpec — 18 Operations for AI Agents
TypeSpec is where API design starts before OpenAPI exists: models, operations, namespaces compiled to specs. act101 navigates those definitions structurally, so agents evolve an API contract at its source of truth.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze TypeSpec code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
Worked TypeSpec examples
act101 reads a TypeSpec file's namespace, model, interface, enum, and import/using directives as top-level declarations: skeleton tags each with its own explicit kind — a namespace module, a model class, an interface interface, an enum enum, and both directive forms import. symbols covers the same top-level set (minus the import/using directives, which it does not read) and reaches one level deeper, into an interface's own operations and an enum's own members, tagging an interface's operations function and an enum's members variable. The unit of structure in this grammar is the namespace-level declaration: skeleton stops there, symbols reaches into interface and enum bodies but not into a model's own properties. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read the API's namespace, models, enum, and interface as a skeleton
conference.tsp declares a ConferenceApi namespace with two models, Session and Speaker, a SessionTrack enum, and a Sessions interface, after importing the @typespec/http library and its TypeSpec.Http namespace.
$ act query skeleton conference.tspBefore
import "@typespec/http";
using TypeSpec.Http;
namespace ConferenceApi;
model Session {
id: string;
title: string;
speakerId: string;
durationMinutes: int32;
}
model Speaker {
id: string;
name: string;
}
enum SessionTrack {
Backend,
Frontend,
Keynote,
}
interface Sessions {
@get listSessions(): Session[];
@post createSession(session: Session): Session;
}Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "import",
"name": "\"@typespec/http\"",
"range": {
"start": {
"file": "conference.tsp",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "conference.tsp",
"line": 1,
"column": 25,
"byte_offset": 24
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 1,
"column": 8,
"byte_offset": 7
},
"end": {
"file": "conference.tsp",
"line": 1,
"column": 24,
"byte_offset": 23
}
}
},
{
"kind": "import",
"name": "TypeSpec.Http",
"range": {
"start": {
"file": "conference.tsp",
"line": 2,
"column": 1,
"byte_offset": 25
},
"end": {
"file": "conference.tsp",
"line": 2,
"column": 21,
"byte_offset": 45
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 2,
"column": 7,
"byte_offset": 31
},
"end": {
"file": "conference.tsp",
"line": 2,
"column": 20,
"byte_offset": 44
}
}
},
{
"kind": "module",
"name": "ConferenceApi",
"range": {
"start": {
"file": "conference.tsp",
"line": 4,
"column": 1,
"byte_offset": 47
},
"end": {
"file": "conference.tsp",
"line": 4,
"column": 25,
"byte_offset": 71
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 4,
"column": 11,
"byte_offset": 57
},
"end": {
"file": "conference.tsp",
"line": 4,
"column": 24,
"byte_offset": 70
}
}
},
{
"kind": "class",
"name": "Session",
"range": {
"start": {
"file": "conference.tsp",
"line": 6,
"column": 1,
"byte_offset": 73
},
"end": {
"file": "conference.tsp",
"line": 11,
"column": 2,
"byte_offset": 168
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 6,
"column": 7,
"byte_offset": 79
},
"end": {
"file": "conference.tsp",
"line": 6,
"column": 14,
"byte_offset": 86
}
}
},
{
"kind": "class",
"name": "Speaker",
"range": {
"start": {
"file": "conference.tsp",
"line": 13,
"column": 1,
"byte_offset": 170
},
"end": {
"file": "conference.tsp",
"line": 16,
"column": 2,
"byte_offset": 217
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 13,
"column": 7,
"byte_offset": 176
},
"end": {
"file": "conference.tsp",
"line": 13,
"column": 14,
"byte_offset": 183
}
}
},
{
"kind": "enum",
"name": "SessionTrack",
"range": {
"start": {
"file": "conference.tsp",
"line": 18,
"column": 1,
"byte_offset": 219
},
"end": {
"file": "conference.tsp",
"line": 22,
"column": 2,
"byte_offset": 274
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 18,
"column": 6,
"byte_offset": 224
},
"end": {
"file": "conference.tsp",
"line": 18,
"column": 18,
"byte_offset": 236
}
}
},
{
"kind": "interface",
"name": "Sessions",
"range": {
"start": {
"file": "conference.tsp",
"line": 24,
"column": 1,
"byte_offset": 276
},
"end": {
"file": "conference.tsp",
"line": 27,
"column": 2,
"byte_offset": 382
}
},
"name_range": {
"start": {
"file": "conference.tsp",
"line": 24,
"column": 11,
"byte_offset": 286
},
"end": {
"file": "conference.tsp",
"line": 24,
"column": 19,
"byte_offset": 294
}
}
}
]
}The skeleton reports seven declarations: both the import statement and the using directive come back kind import, ConferenceApi as module, Session/Speaker as class, SessionTrack as enum, and Sessions as interface — the interface's own two operations are not read at this level.
List the enum's members and interface's operations as symbols
SessionTrack enumerates Backend, Frontend, and Keynote; Sessions declares listSessions and createSession, each decorated with its HTTP verb.
$ act query symbols conference.tspBefore
import "@typespec/http";
using TypeSpec.Http;
namespace ConferenceApi;
model Session {
id: string;
title: string;
speakerId: string;
durationMinutes: int32;
}
model Speaker {
id: string;
name: string;
}
enum SessionTrack {
Backend,
Frontend,
Keynote,
}
interface Sessions {
@get listSessions(): Session[];
@post createSession(session: Session): Session;
}Output
{
"type": "Symbols",
"symbols": [
{
"name": "ConferenceApi",
"kind": "module",
"range": {
"start": {
"file": "conference.tsp",
"line": 4,
"column": 11,
"byte_offset": 57
},
"end": {
"file": "conference.tsp",
"line": 4,
"column": 24,
"byte_offset": 70
}
},
"visibility": "unknown"
},
{
"name": "Session",
"kind": "class",
"range": {
"start": {
"file": "conference.tsp",
"line": 6,
"column": 7,
"byte_offset": 79
},
"end": {
"file": "conference.tsp",
"line": 6,
"column": 14,
"byte_offset": 86
}
},
"visibility": "unknown"
},
{
"name": "Speaker",
"kind": "class",
"range": {
"start": {
"file": "conference.tsp",
"line": 13,
"column": 7,
"byte_offset": 176
},
"end": {
"file": "conference.tsp",
"line": 13,
"column": 14,
"byte_offset": 183
}
},
"visibility": "unknown"
},
{
"name": "SessionTrack",
"kind": "enum",
"range": {
"start": {
"file": "conference.tsp",
"line": 18,
"column": 6,
"byte_offset": 224
},
"end": {
"file": "conference.tsp",
"line": 18,
"column": 18,
"byte_offset": 236
}
},
"visibility": "unknown"
},
{
"name": "Backend",
"kind": "variable",
"range": {
"start": {
"file": "conference.tsp",
"line": 19,
"column": 3,
"byte_offset": 241
},
"end": {
"file": "conference.tsp",
"line": 19,
"column": 10,
"byte_offset": 248
}
},
"visibility": "unknown"
},
{
"name": "Frontend",
"kind": "variable",
"range": {
"start": {
"file": "conference.tsp",
"line": 20,
"column": 3,
"byte_offset": 252
},
"end": {
"file": "conference.tsp",
"line": 20,
"column": 11,
"byte_offset": 260
}
},
"visibility": "unknown"
},
{
"name": "Keynote",
"kind": "variable",
"range": {
"start": {
"file": "conference.tsp",
"line": 21,
"column": 3,
"byte_offset": 264
},
"end": {
"file": "conference.tsp",
"line": 21,
"column": 10,
"byte_offset": 271
}
},
"visibility": "unknown"
},
{
"name": "Sessions",
"kind": "interface",
"range": {
"start": {
"file": "conference.tsp",
"line": 24,
"column": 11,
"byte_offset": 286
},
"end": {
"file": "conference.tsp",
"line": 24,
"column": 19,
"byte_offset": 294
}
},
"visibility": "unknown"
},
{
"name": "listSessions",
"kind": "function",
"range": {
"start": {
"file": "conference.tsp",
"line": 25,
"column": 8,
"byte_offset": 304
},
"end": {
"file": "conference.tsp",
"line": 25,
"column": 20,
"byte_offset": 316
}
},
"visibility": "unknown"
},
{
"name": "createSession",
"kind": "function",
"range": {
"start": {
"file": "conference.tsp",
"line": 26,
"column": 9,
"byte_offset": 339
},
"end": {
"file": "conference.tsp",
"line": 26,
"column": 22,
"byte_offset": 352
}
},
"visibility": "unknown"
}
]
}symbols drops both the import and using directives, for ten entries, and adds SessionTrack's three members as kind variable and Sessions's two operations as kind function — Session and Speaker's own properties are still not read.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch