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

# Prompt Definition

> Reference for Redop prompt fields, prompt argument behavior, argumentsSchema, and how both fields are resolved together.

Prompt definitions register MCP prompts and control prompt metadata, handler input, prompt-local hooks, and middleware.

## Example with `arguments`

```ts theme={null}
app.prompt("summarise", {
  description: "Summarise a block of text",
  arguments: [
    { name: "text", required: true },
    { name: "length" },
  ],
  afterResponse: async ({ name, result, error }) => {},
  handler: ({ arguments: args, request }) => ({
    description: "Summarise user-provided text",
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Summarise this for ${request.transport}: ${args.text}`,
        },
      },
    ],
  }),
});
```

## Example with `argumentsSchema`

```ts theme={null}
import { z } from "zod";

app.prompt("summarise", {
  description: "Summarise a topic",
  argumentsSchema: z.object({
    limit: z.coerce.number().int().min(1),
    topic: z.string().min(1),
  }),
  handler: ({ arguments: args }) => ({
    description: "Summarise a topic with a target sentence count",
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Summarise ${args.topic} in ${args.limit} sentences.`,
        },
      },
    ],
  }),
});
```

## Fields

| Field             | Required | Purpose                                                                                                                         |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `description`     | No       | Short prompt description.                                                                                                       |
| `arguments`       | No       | Named prompt arguments exposed to clients and used for required-argument checks.                                                |
| `argumentsSchema` | No       | Schema used to parse and validate prompt arguments before the handler runs.                                                     |
| `before`          | No       | Prompt-local hook that runs before middleware and the handler.                                                                  |
| `after`           | No       | Prompt-local hook that runs after a successful result and may replace it.                                                       |
| `afterResponse`   | No       | Prompt-local hook that runs after the response is written. Receives either `result` or `error` and cannot replace the response. |
| `middleware`      | No       | Middleware scoped to this prompt only.                                                                                          |
| `handler`         | Yes      | Returns prompt messages or `{ description?, messages }`.                                                                        |

## `arguments`

When you register a prompt with a literal `arguments` array, Redop infers the handler `arguments` shape from that definition.

* `{ name: "text", required: true }` becomes `arguments.text: string`
* `{ name: "length" }` becomes `arguments.length?: string`
* prompts without an `arguments` definition receive `arguments` as `undefined`

Redop also rejects prompt calls that omit required arguments.

## `argumentsSchema`

`argumentsSchema` accepts the same schema styles Redop supports for tool `inputSchema`.

* Standard Schema V1 libraries such as Zod, Valibot, and ArkType
* TypeBox
* plain JSON Schema

When `argumentsSchema` is present, the prompt handler receives the parsed schema output instead of a raw `Record<string, string>`.

If you omit `arguments`, Redop derives prompt argument metadata from an object-shaped `argumentsSchema` when possible.

## When both are defined

Defining both `arguments` and `argumentsSchema` does not throw by itself.

Redop resolves them like this:

* `arguments` controls prompt metadata returned to clients
* `arguments` drives the early missing-required-argument check
* `argumentsSchema` parses and validates the incoming arguments
* `argumentsSchema` determines the handler `arguments` type

This means the handler follows the schema output, not the string shape declared in `arguments`, when both are present.

If the two definitions disagree, metadata and runtime validation can drift. Redop does not currently reject that mismatch automatically.

Use both fields only when you need custom metadata and schema-based parsing at the same time, and keep them aligned.

## Prompt naming

Prompt names are validated when you call `.prompt(name, def)`.

* use a stable identifier such as `code_review` or `summarise`
* keep names within 64 characters
* use letters, numbers, `_`, `-`, `.`, and `/`
* avoid spaces and trailing whitespace

## Prompt message content

Prompt messages can contain:

* text
* image data
* embedded resource payloads

## Notes

* Use `afterResponse` for analytics or logging that should happen after the prompt response is already sent.
* Use `after` instead when the logic must still be able to replace the successful prompt result.