> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Reference

> Complete Zod schema definitions used across Toolshed.

All schemas are exported from `@toolshed/shared`.

## ToolDefinitionSchema

```typescript theme={null}
z.object({
  path: z.string().regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/),
  name: z.string(),
  description: z.string(),
  inputSchema: z.record(z.unknown()),        // JSON Schema object
  outputSchema: z.record(z.unknown()).optional(),
  destructive: z.boolean().default(false),
  authProvider: z.string().optional(),
  serviceAccountAllowed: z.boolean().default(false),
  metadata: z.object({
    httpMethod: z.string().optional(),
    operationType: z.enum(["query", "mutation"]).optional(),
    mcpAnnotations: z.record(z.unknown()).optional(),
  }).optional(),
})
```

## RoleSchema

```typescript theme={null}
z.object({
  id: z.string(),
  name: z.string(),
  patterns: z.array(z.string()),
})
```

## AuditEntrySchema

```typescript theme={null}
z.object({
  id: z.string(),
  userId: z.string(),
  roleId: z.string(),
  toolPath: z.string(),
  args: z.record(z.unknown()).optional(),
  resultStatus: z.enum(["success", "error", "denied", "elicited"]),
  elicitTrail: z.array(z.string()).optional(),
  timestamp: z.string().datetime(),
})
```

## ElicitationRequestSchema

```typescript theme={null}
z.object({
  executionId: z.string(),
  toolPath: z.string(),
  message: z.string(),
  args: z.record(z.unknown()).optional(),
  type: z.enum(["approval", "form"]).default("approval"),
})
```

## ElicitationResponseSchema

```typescript theme={null}
z.object({
  executionId: z.string(),
  approved: z.boolean(),
  data: z.record(z.unknown()).optional(),
})
```

<Note>
  The response uses an `approved` boolean field, not a status string. This is the canonical shape for resolved elicitations.
</Note>

## SerializedCatalogSchema

```typescript theme={null}
z.object({
  version: z.literal("v1"),
  types: z.record(JsonSchemaSchema),
  tools: z.array(ToolRegistrationSchema),
  sources: z.array(SourceRegistrationSchema),
})
```

## ToolRegistrationSchema

```typescript theme={null}
z.object({
  path: z.string(),
  name: z.string(),
  description: z.string(),
  sourceId: z.string(),
  inputSchemaRef: z.string(),              // Key into the types dictionary
  outputSchemaRef: z.string().optional(),
  destructive: z.boolean(),
  authProvider: z.string().optional(),
  serviceAccountAllowed: z.boolean(),
})
```

## SourceRegistrationSchema

```typescript theme={null}
z.object({
  id: z.string(),
  type: z.enum(["openapi", "mcp", "graphql", "plugin"]),
  name: z.string(),
  description: z.string(),
  toolCount: z.number().int().nonnegative(),
})
```

## RunRequestSchema

```typescript theme={null}
z.object({
  script: z.string(),
  userId: z.string(),
})
```

## SearchToolsRequestSchema

```typescript theme={null}
z.object({
  query: z.string(),
  limit: z.number().int().positive().default(10),
})
```

## ReadToolRequestSchema

```typescript theme={null}
z.object({
  path: z.string(),
})
```

## ResumeRequestSchema

```typescript theme={null}
z.object({
  executionId: z.string(),
  response: ElicitationResponseSchema,
})
```