tapimo 0.4.1 → 0.4.3

package/src/apps/management/routes/orgs.test.ts

@@ -12,14 +12,30 @@ const origin = 'http://localhost'
 /** Super admin secret configured on the test app. */
 const secret = 'tempo:sk:b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1'
 
-/** Wildcard-scoped key: full data access, still not a super admin. */
+/** Wildcard-scoped key: full API access, still not a super admin. */
 const wildcard = {
   id: 'key_wildcard',
-  orgId: 'org_test',
+  orgId: 'org_a',
   scopes: ['*'],
   token: 'secret_wildcard_key',
 } satisfies TestApp.kvStore.Key
 
+/** Key limited to management reads for Org A. */
+const managementRead = {
+  id: 'key_management_read',
+  orgId: 'org_a',
+  scopes: ['management:read'],
+  token: 'secret_management_read_key',
+} satisfies TestApp.kvStore.Key
+
+/** Key limited to management writes for Org A. */
+const managementWrite = {
+  id: 'key_management_write',
+  orgId: 'org_a',
+  scopes: ['management:write'],
+  token: 'secret_management_write_key',
+} satisfies TestApp.kvStore.Key
+
 /** RequestInit presenting the given token. */
 function as(token: string) {
   return { headers: { 'tempo-api-key': token } } as const
@@ -36,7 +52,10 @@ function json(method: 'PATCH' | 'POST', cookie: string, body: unknown) {
 
 function createApp(db = TestApp.database()) {
   return TestApp.create({
-    auth: { keys: [TestApp.key, wildcard], superAdmin: { secret } },
+    auth: {
+      keys: [TestApp.key, managementRead, managementWrite, wildcard],
+      superAdmin: { secret },
+    },
     db,
     session: { wallet: { origin } },
   })
@@ -81,6 +100,19 @@ describe('GET /orgs', () => {
     `)
   })
 
+  test('accepts a management API key in the query parameter', async () => {
+    const app = await seeded()
+    const response = await app.request(`/v1/orgs?key=${encodeURIComponent(managementRead.token)}`)
+    const body = await TestApp.json(response, Orgs.schema.listOrganizations.Response)
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    expect(body.data.map(({ id }) => id)).toMatchInlineSnapshot(`
+      [
+        "org_a",
+      ]
+    `)
+  })
+
   test('lists only owned organizations for a session', async () => {
     const app = await seeded()
     const cookie = await session(app)
@@ -112,24 +144,26 @@ describe('GET /orgs', () => {
     `)
   })
 
-  test('rejects API keys without the wildcard scope', async () => {
+  test('rejects API keys without the management read scope', async () => {
     const response = await (await seeded()).request('/v1/orgs', as(TestApp.key.token))
     expect(response.status).toBe(403)
   })
 
-  test('rejects wildcard API keys', async () => {
+  test('lists only the owning organization for scoped and wildcard keys', async () => {
+    const app = await seeded()
+    const scoped = await app.request('/v1/orgs', as(managementRead.token))
+    expect(scoped.status).toBe(200)
+    expect(
+      (await TestApp.json(scoped, Orgs.schema.listOrganizations.Response)).data.map(({ id }) => id),
+    ).toEqual(['org_a'])
+
     const response = await (await seeded()).request('/v1/orgs', as(wildcard.token))
-    expect(response.status).toBe(403)
-    const { requestId, ...body } = (await response.json()) as { requestId?: string }
-    expect(requestId).toBeDefined()
-    expect(body).toMatchInlineSnapshot(`
-      {
-        "error": {
-          "code": "forbidden",
-          "message": "API key not permitted for this route",
-        },
-      }
-    `)
+    expect(response.status).toBe(200)
+    expect(
+      (await TestApp.json(response, Orgs.schema.listOrganizations.Response)).data.map(
+        ({ id }) => id,
+      ),
+    ).toEqual(['org_a'])
   })
 
   test('rejects the secret when super admin is unconfigured', async () => {
@@ -200,6 +234,13 @@ describe('POST /orgs', () => {
 })
 
 describe('GET /orgs/:orgId', () => {
+  test('binds API keys to their owning organization', async () => {
+    const app = await seeded()
+    expect((await app.request('/v1/orgs/org_a', as(managementRead.token))).status).toBe(200)
+    expect((await app.request('/v1/orgs/org_b', as(managementRead.token))).status).toBe(404)
+    expect((await app.request('/v1/orgs/org_a', as(managementWrite.token))).status).toBe(403)
+  })
+
   test('hides foreign organizations behind 404', async () => {
     const app = createApp()
     const owner = await session(app)
@@ -219,6 +260,27 @@ describe('GET /orgs/:orgId', () => {
 })
 
 describe('PATCH /orgs/:orgId', () => {
+  test('requires the management write scope', async () => {
+    const app = await seeded()
+    const write = await app.request(
+      `/v1/orgs/org_a?key=${encodeURIComponent(managementWrite.token)}`,
+      {
+        body: JSON.stringify({ name: 'Managed' }),
+        headers: { 'content-type': 'application/json' },
+        method: 'PATCH',
+      },
+    )
+    expect(write.status).toBe(200)
+    expect((await TestApp.json(write, Orgs.schema.Organization)).name).toBe('Managed')
+
+    const readOnly = await app.request('/v1/orgs/org_a', {
+      body: JSON.stringify({ name: 'Denied' }),
+      headers: { 'content-type': 'application/json', 'tempo-api-key': managementRead.token },
+      method: 'PATCH',
+    })
+    expect(readOnly.status).toBe(403)
+  })
+
   test('renames an owned organization', async () => {
     const app = createApp()
     const cookie = await session(app)

package/src/apps/management/routes/orgs.ts

@@ -46,7 +46,7 @@ export namespace schema {
       role: z
         .optional(z.enum(Memberships.roles))
         .check(
-          z.describe("The caller's role in this organization; absent for the super admin."),
+          z.describe("The caller's role; absent for API keys and the super admin."),
           z.meta({ examples: ['owner'] }),
         ),
       updatedAt: z
@@ -104,17 +104,13 @@ export namespace schema {
 }
 
 /**
- * Mounts the `/orgs` resource: session-owned tenancy (each organization is
- * owned by the user that created it). The super admin bypasses ownership;
- * inaccessible or absent ids render `404` so foreign org ids are
- * indistinguishable from missing ones. Projects nest under `/orgs/:orgId` in
- * the projects app.
+ * Mounts organizations. Sessions access memberships, API keys access their owning organization, and the super admin bypasses ownership.
  */
 export function orgs() {
   return new Hono<App.Environment>()
     .get(
       '/v1/orgs',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       OpenApi.describeRoute({
         operationId: 'listOrganizations',
         responses: OpenApi.responses({
@@ -127,18 +123,21 @@ export function orgs() {
         tags: ['Organizations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
-
-        const principal = Auth.getPrincipal(c)
-        if (principal?.type !== 'session' && principal?.type !== 'super_admin')
-          return sessionRequired(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
 
         const db = Db.get(c.get('db'))
         try {
+          const principal = Auth.getPrincipal(c)
+          if (!principal || principal.type === 'public')
+            throw new Error('organization auth policy admitted an unsupported principal')
           const records =
             principal.type === 'super_admin'
               ? await Organizations.list(db)
-              : await Organizations.listByMember(db, principal.id)
+              : principal.type === 'api_key'
+                ? [await Organizations.get(db, principal.orgId)].filter(
+                    (record): record is Organizations.Record => record !== undefined,
+                  )
+                : await Organizations.listByMember(db, principal.id)
           return c.json(
             Response.validated(schema.listOrganizations.Response, {
               data: records.map(serializeOrganization),
@@ -203,7 +202,7 @@ export function orgs() {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -219,7 +218,7 @@ export function orgs() {
         tags: ['Organizations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -238,7 +237,7 @@ export function orgs() {
     )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -258,7 +257,7 @@ export function orgs() {
         tags: ['Organizations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -289,7 +288,7 @@ export function orgs() {
     )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'owner' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -309,7 +308,7 @@ export function orgs() {
         tags: ['Organizations'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -321,7 +320,9 @@ export function orgs() {
         try {
           const kv = c.get('kv')
           if (kv)
-            for (const record of await ApiKeys.listByOrg(kv.store, Auth.org(c).id))
+            for (const record of await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
+              scopeCatalog: c.get('scopeCatalog'),
+            }))
               await ApiKeys.revoke(kv.store, record.id)
           const deleted = await Organizations.deleteOrganization(db, Auth.org(c).id)
           if (!deleted) return organizationNotFound(c)

package/src/apps/management/routes/projects.ts

@@ -125,15 +125,13 @@ export namespace schema {
 }
 
 /**
- * Mounts the `/orgs/:orgId/projects` resource: projects nested under their
- * owning organization. Access follows the org scope (owning session or super
- * admin); inaccessible or absent ids render `404`.
+ * Mounts projects under their owning organization. Access follows the scoped session, API key, or super admin; inaccessible projects return `404`.
  */
 export function projects() {
   return new Hono<App.Environment>()
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -152,7 +150,7 @@ export function projects() {
         tags: ['Projects'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -176,7 +174,7 @@ export function projects() {
     )
     .post(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       OpenApi.validate('param', schema.Params, {
         code: 'param_invalid',
@@ -196,7 +194,7 @@ export function projects() {
         tags: ['Projects'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -221,7 +219,7 @@ export function projects() {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.ProjectParams, {
@@ -238,7 +236,7 @@ export function projects() {
         tags: ['Projects'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -251,7 +249,7 @@ export function projects() {
     )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.ProjectParams, {
@@ -272,7 +270,7 @@ export function projects() {
         tags: ['Projects'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'param_invalid',
@@ -298,7 +296,7 @@ export function projects() {
     )
     .delete(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/projects/:projectId{prj_[A-Za-z0-9_-]+}',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
       Auth.ensureOrg({ role: 'admin' }),
       Auth.ensureProject(),
       OpenApi.validate('param', schema.ProjectParams, {
@@ -318,7 +316,7 @@ export function projects() {
         tags: ['Projects'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureProjectError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -332,6 +330,7 @@ export function projects() {
           if (kv)
             for (const record of await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
               projectId: Auth.project(c).id,
+              scopeCatalog: c.get('scopeCatalog'),
             }))
               await ApiKeys.revoke(kv.store, record.id)
           const deleted = await Projects.deleteProject(db, Auth.project(c).id)

package/src/apps/management/routes/scopes.test.ts

@@ -19,6 +19,8 @@ describe('scopes', () => {
       [
         "data:read",
         "indexer:query",
+        "management:read",
+        "management:write",
         "rpc-relay:read",
         "rpc-relay:sponsor",
         "webhooks:read",
@@ -26,4 +28,18 @@ describe('scopes', () => {
       ]
     `)
   })
+
+  test('includes host scopes configured on the app', async () => {
+    const custom = {
+      description: 'Read project accounts.',
+      scope: 'accounts:read',
+      selfServe: true,
+    } as const satisfies Scope.Entry
+    const app = TestApp.create({ scopes: [custom] })
+    const response = await app.request('/v1/scopes')
+    const body = await TestApp.json(response, Scopes.schema.getScopes.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.data).toEqual([...Scope.catalog, custom])
+  })
 })

package/src/apps/management/routes/scopes.ts

@@ -6,7 +6,6 @@ import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
-import * as Scope from '../../../Scope.js'
 
 /** Zod schemas owned by the scope-catalog resource. */
 export namespace schema {
@@ -22,7 +21,7 @@ export namespace schema {
             z.meta({ examples: ['Read webhook subscriptions.'] }),
           ),
         scope: z
-          .enum(Scope.catalog.map((entry) => entry.scope))
+          .string()
           .check(
             z.describe('Scope identifier used in API-key grants and route policies.'),
             z.meta({ examples: ['data:read'] }),
@@ -30,7 +29,7 @@ export namespace schema {
         selfServe: z
           .boolean()
           .check(
-            z.describe('Whether a session may self-mint this scope (else super-admin-only).'),
+            z.describe('Whether an eligible session may self-mint this scope.'),
             z.meta({ examples: [true] }),
           ),
       })
@@ -47,13 +46,13 @@ export namespace schema {
 
 /**
  * Mounts the `/scopes` resource: the issuable API-key scope vocabulary, served
- * from {@link Scope.catalog}. Public catalog data: anonymous callers are served
+ * from the configured catalog. Public catalog data: anonymous callers are served
  * within the public quota; the session lane lets signed-in consoles skip it.
  */
 export function scopes() {
   return new Hono<App.Environment>().get(
     '/v1/scopes',
-    Auth.policy({ public: true, session: true }),
+    Auth.policy({ apiKey: { scopes: [] }, public: true, session: true }),
     OpenApi.describeRoute({
       description: 'See which scopes can be granted to API keys.',
       operationId: 'getScopes',
@@ -65,7 +64,7 @@ export function scopes() {
     }),
     Cache.response<App.Environment>({
       cacheControl: Cache.policies.stable,
-      name: 'tempo-api:scopes:v1',
+      name: 'tempo-api:scopes:v2',
       key: (c) => {
         const url = new URL(c.req.url)
         url.search = ''
@@ -76,7 +75,7 @@ export function scopes() {
       if (Auth.narrowAccess) return Auth.accessError(c)
       return c.json(
         Response.validated(schema.getScopes.Response, {
-          data: Scope.catalog.map((entry) => ({ ...entry })),
+          data: c.get('scopeCatalog').map((entry) => ({ ...entry })),
         }),
         200,
       )

package/src/apps/management/routes/usage.ts

@@ -285,16 +285,12 @@ export namespace schema {
   }
 }
 
-/**
- * Mounts the usage surface: project request usage (read from a host-supplied
- * analytics capability) and an organization's sponsorship volume and fees
- * over time. Session lane; reads for members.
- */
+/** Mounts organization request and sponsorship usage. Reads require membership or a scoped API key. */
 export function usage() {
   return new Hono<Environment>()
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/usage/requests',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.getRequestUsage.Params, {
         code: 'param_invalid',
@@ -327,7 +323,7 @@ export function usage() {
         tags: ['Usage'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -398,7 +394,7 @@ export function usage() {
     )
     .get(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/usage/sponsorships',
-      Auth.policy({ session: true }),
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, session: true }),
       Auth.ensureOrg(),
       OpenApi.validate('param', schema.getSponsorshipUsage.Params, {
         code: 'param_invalid',
@@ -423,7 +419,7 @@ export function usage() {
         tags: ['Usage'],
       }),
       async (c) => {
-        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowAccess) return Auth.accessError(c)
         if (Auth.narrowScope) return Auth.ensureOrgError(c)
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -498,11 +494,10 @@ async function legacyKeyIds(
 ): Promise<readonly string[]> {
   const kv = c.get('kv')
   if (!kv) return []
-  const records = await ApiKeys.listByOrg(
-    kv.store,
-    Auth.org(c).id,
-    options.projectId === undefined ? {} : { projectId: options.projectId },
-  )
+  const records = await ApiKeys.listByOrg(kv.store, Auth.org(c).id, {
+    ...(options.projectId === undefined ? {} : { projectId: options.projectId }),
+    scopeCatalog: c.get('scopeCatalog'),
+  })
   return records
     .filter(
       (record) => options.environment === undefined || record.environment === options.environment,

package/src/apps/mcp.test.ts

@@ -121,6 +121,30 @@ test('scopes tools to the data domain', async () => {
   expect(tools.some((name) => name.startsWith('v1_me'))).toBe(false)
 })
 
+test('keeps tool input schemas compact', async () => {
+  const { host } = createHost()
+  await initialize(host)
+
+  const body = await request(host, { id: 2, jsonrpc: '2.0', method: 'tools/list', params: {} })
+  const tools = body.result.tools as {
+    name: string
+    inputSchema: { properties?: Record<string, { description?: string }> }
+  }[]
+  const tool = tools.find((entry) => entry.name === 'v1_tokens_get')
+  const properties = tool?.inputSchema.properties ?? {}
+
+  // Credential inputs stay off the schema; auth rides the forwarded header.
+  expect(properties['authorization']).toBeUndefined()
+  expect(properties['tempo-api-key']).toBeUndefined()
+  // Shared parameters carry the terse tool descriptions.
+  expect(properties['limit']?.description).toBe('Items per page.')
+  expect(properties['cursor']?.description).toBe(
+    'Keyset cursor from a previous response `nextCursor`; omit for the first page.',
+  )
+  // `compact` strips examples from generated schemas.
+  expect(JSON.stringify(tool?.inputSchema)).not.toContain('"examples"')
+})
+
 test('executes generated tools against the composed app', async () => {
   // Verified tokens are database-backed, so seed the default chain.
   const db = TestApp.database()
@@ -176,7 +200,7 @@ test('documents POST /mcp and keeps it open under auth enforcement', async () =>
   expect(operation?.operationId).toBe('mcpRequest')
   expect(operation?.tags).toEqual(['MCP'])
   // Anonymous and any-valid-key access; no required scopes.
-  expect(operation?.security).toEqual([{ apiKey: [] }, { bearerAuth: [] }, {}])
+  expect(operation?.security).toEqual([{ apiKey: [] }, { queryApiKey: [] }, { bearerAuth: [] }, {}])
 
   // Surfaces under `Data API` in the reference, but the tool filter excludes the `MCP` tag.
   const groups = Object.fromEntries(spec['x-tagGroups'].map((group) => [group.name, group.tags]))

package/src/apps/mcp.ts

@@ -15,7 +15,7 @@ const excludedTags = ['CoinGecko', 'MCP']
 
 /** Usage guidance surfaced to MCP clients on initialize. */
 const instructions =
-  "Tools mirror the Tempo API's data domain. Authenticated tools accept a Tempo API key: send it as an `Authorization: Bearer` header on the HTTP request, or pass the `authorization` tool input per call. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation."
+  "Tools mirror the Tempo API's data domain. Authenticated tools accept a Tempo API key sent as an `Authorization: Bearer` header on the HTTP request. List endpoints paginate via `cursor`/`nextCursor`. `docs_*` tools search the Tempo documentation."
 
 /** Zod schemas owned by the MCP endpoint's OpenAPI description. */
 export namespace schema {
@@ -97,7 +97,15 @@ export function mcp(options: mcp.Options) {
       },
       mcp: { instructions },
       openapi: scope(document),
-      openapiConfig: { forwardHeaders: ['authorization'], mode: 'namespace' },
+      // `compact` + `security: false` keep tool schemas lean: no examples,
+      // oversized regexes, or per-tool credential inputs (auth rides the
+      // forwarded `Authorization` header).
+      openapiConfig: {
+        compact: true,
+        forwardHeaders: ['authorization'],
+        mode: 'namespace',
+        security: false,
+      },
       version,
     })
     if (docs !== false)
@@ -217,11 +225,43 @@ function scope(document: Document): Openapi.OpenAPISpec {
       return tags_operation?.some((tag) => tags.has(tag)) ?? false
     })
     if (entries.some(([method]) => methods.includes(method)))
-      paths[path] = Object.fromEntries(entries)
+      paths[path] = Object.fromEntries(
+        entries.map(([method, operation]) =>
+          methods.includes(method) ? [method, condense(operation)] : [method, operation],
+        ),
+      )
   }
   return { ...document, paths }
 }
 
+/** Terse tool descriptions for parameters repeated across most operations; the public document keeps the full prose. */
+const parameterDescriptions: Record<string, string> = {
+  chainId: 'Chain: `mainnet` (default), `testnet`, or a numeric chain id.',
+  cursor: 'Keyset cursor from a previous response `nextCursor`; omit for the first page.',
+  include: 'Comma-separated related resources to include.',
+  limit: 'Items per page.',
+  order: 'Sort order: `asc` or `desc` (default).',
+  page: '1-indexed page number; mutually exclusive with `cursor`.',
+}
+
+/** Swaps shared query-parameter prose for the terse tool descriptions. */
+function condense(operation: unknown) {
+  const { parameters } = operation as {
+    parameters?: readonly { in?: string; name?: string }[] | undefined
+  }
+  if (!parameters) return operation
+  return {
+    ...(operation as object),
+    parameters: parameters.map((parameter) => {
+      const description =
+        parameter.in === 'query' && parameter.name
+          ? parameterDescriptions[parameter.name]
+          : undefined
+      return description ? { ...parameter, description } : parameter
+    }),
+  }
+}
+
 export declare namespace mcp {
   /** Options for the MCP route group. */
   type Options = {