# Golem Annotate Agent TS

> Adding prompt and description annotations to TypeScript agents and their methods. Use when the user asks to add descriptions, prompts, or documentation metadata to agent classes or methods for AI/LLM discovery.

- Skill: `golemcloud/golem-annotate-agent-ts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add golemcloud/golem-annotate-agent-ts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/golemcloud/golem-annotate-agent-ts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: golemcloud (https://skillmd.com/u/golemcloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/golemcloud/golem-annotate-agent-ts

---


# Annotating Agents and Methods (TypeScript)

## Overview

Golem agents can annotate the agent and its methods with human-readable metadata. This metadata drives AI/LLM tool discovery — agents with annotations can be used as tools by LLM-based systems. In the TypeScript SDK the annotations are plain fields on the `defineAgent(...)` spec and on each `method(...)`.

## Annotations

- **`promptHint`** — a short instruction telling an LLM *when* to call this method
- **`description`** — a longer explanation of what the agent or method does, its parameters, and return value

## Agent-Level Annotations

To describe the agent itself (its overall purpose), set `description` (and optionally `promptHint`) as top-level fields on the `defineAgent(...)` spec:

```typescript
import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';

export const ProfileAgent = defineAgent({
    name: 'ProfileAgent',
    description: 'Handles user profile management and preferences',
    id: { userId: z.string() },
    http: http.mount('/api/v1/profiles/{userId}'),
    methods: { /* ... */ },
});
```

## Method-Level Annotations

Set `description` and `promptHint` inside the `method({...})` call for each method:

```typescript
import { z } from 'zod';
import { defineAgent, method, http } from '@golemcloud/golem-ts-sdk';

export const InventoryAgent = defineAgent({
    name: 'InventoryAgent',
    description: 'Manages product inventory for a warehouse',
    id: { warehouseId: z.string() },
    http: http.mount('/warehouses/{warehouseId}'),
    methods: {
        checkStock: method({
            input: { sku: z.string() },
            returns: z.number(),
            promptHint: 'Look up the current stock level for a product',
            description:
                'Returns the number of units in stock for the given product SKU. Returns 0 if the product is not found.',
        }),
        restock: method({
            input: { sku: z.string(), quantity: z.number() },
            returns: z.number(),
            promptHint: 'Add units of a product to inventory',
            description:
                'Increases the stock count for the given SKU by the specified amount. Returns the new total.',
        }),
        pick: method({
            input: { sku: z.string(), quantity: z.number() },
            returns: z.number(),
            promptHint: 'Remove units of a product from inventory',
            description: 'Decreases the stock count for the given SKU. Throws if insufficient stock.',
        }),
    },
});
```

## Guidelines

- `description` on the **agent** spec describes the agent's overall purpose for LLM discovery
- `promptHint` on a **method** should be a natural-language instruction an LLM can match against a user request
- `description` on a **method** should document behavior, edge cases, and expected inputs/outputs
- All of these fields are optional — omit them for internal methods not intended for LLM discovery
- Annotations have no effect on runtime behavior; they are purely metadata