golem-annotate-agent-ts

name	golem-annotate-agent-ts
description	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.

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:

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:

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.',
        }),
        : ({
            : { : z.(), : z.() },
            : z.(),
            : ,
            : ,
        }),
    },
});

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