> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/flowai/agent-projects/configure-decorator-schemas/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure a decorator's JSON schema

> Set default values, restrict allowed values, limit which fields an agent can use, and add clarifying descriptions in a decorator's JSON schema.

A decorator's JSON schema lets you refine how an agent uses a tool's inputs, beyond what the tool's own schema provides. For example, you can set a default value, restrict allowed values, or limit which fields the agent can use. This is more reliable than pasting example payloads into the prompt.

See the following [examples](#examples) for ideas.

## Before you begin

* **Know how to create or clone a decorator.** This guide assumes you're already at the **Schema** field on the **Create Decorator** page. For that procedure, see [Schema decorators](/itential-platform/flowai/agent-projects/agent-builder#schema-decorators).
* **Know your starting schema.** Every change below builds on what's already in the **Schema**, so review it before you add a default, restriction, or removal. When you create a new decorator, that's the tool's original schema. When you clone one, it's the schema of the decorator you cloned.
* **Have a working familiarity with JSON schemas.** The **Schema** field uses the same type system as the [JSON Schema standard](https://json-schema.org/overview/what-is-jsonschema). If you haven't written a schema by hand before, start with that guide. It covers the same `type`, `properties`, `required`, and `description` keywords referenced below.
* **Have permission to create a decorator** for the tool. For the specific permissions, see [Access control](/itential-platform/flowai/agent-projects/agent-builder#access-control).

## Understand decorator schemas

A decorator's **Schema** is a single JSON code editor with search and copy-to-clipboard actions built into its toolbar.

When you create a new decorator, Itential pre-populates this field with the tool's own JSON schema, which is the same schema already defined for that adapter, application, or integration method. It can include details beyond basic types, such as `pattern`, `title`, or `examples`, if that schema includes them.

For more information about working with schemas, see [Schema decorators](/itential-platform/flowai/agent-projects/agent-builder#schema-decorators).

## Examples

### Assign a default value to an input field

Set a default when the tool consistently expects the same value for a field. This reduces how often the agent has to reason about a parameter it doesn't have strong context for, and prevents empty submissions.

Open **Create Decorator**, either by creating a new decorator or by cloning an existing one.

Locate the property definition for the field you want to default in the **Schema** field.

Add a `default` keyword to that property, set to the value you want.

Click **Save Decorator**.

```json
{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "default": "amer-east"
    }
  }
}
```

A `default` only applies when the agent omits the field. It doesn't stop the agent from sending a different value. To constrain what the agent can send, use `enum`, described next.

### Restrict the allowed values for an input field

Use `enum` to give the agent a closed list of valid values instead of an open string or number field. This prevents the agent from guessing at a value that isn't valid for the tool.

Open **Create Decorator**, either by creating a new decorator or by cloning an existing one.

Locate the property definition for the field you want to restrict in the **Schema** field.

Add an `enum` array listing every value you want to allow.

Click **Save Decorator**.

```json
{
  "type": "object",
  "properties": {
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  }
}
```

You can combine `enum` with `default` on the same property. In the example above, adding `"default": "medium"` gives the agent a fallback while still limiting it to the three listed values.

### Restrict the agent to specific input fields

Some tools expose several optional fields that you don't want the agent using, even though the underlying tool supports them. This is different from marking a field required. `required` only guarantees a field always has a value; it doesn't stop the agent from also using other optional fields still in the schema.

> **Note**
>
> Removing a property from a decorator's schema doesn't remove it from the tool itself. It only limits what the agent sees as an input option.

To limit which fields the agent can use:

Open **Create Decorator**, either by creating a new decorator or by cloning an existing one.

In the **Schema** field, remove the property definitions for any fields you don't want the agent to use. The schema starts as a copy, either of the tool's full set of properties or of the cloned decorator's, so this usually means deleting entries rather than adding restrictions to nothing.

Add the fields that must always have a value to the `required` array.

(Optional) Set `"additionalProperties": false` at the schema level. This blocks the agent from sending any field beyond what you explicitly define, even if the tool itself would accept it.

Click **Save Decorator**.

```json
{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    }
  },
  "required": ["hostname"],
  "additionalProperties": false
}
```

### Add a description to clarify what an input field is for

A tool's original schema may give an input field a generic or missing description. The agent then knows a field's type, but not what the value represents or where it should come from. Update the `description` keyword for a property to spell that out directly, for example by pointing the agent to the right upstream source for a value instead of leaving it to guess.

Open **Create Decorator**, either by creating a new decorator or by cloning an existing one.

Locate the property definition for the input field you want to clarify in the **Schema** field.

Add or update the `description` value with specific, task-relevant guidance, such as what the value represents or where the agent should get it from.

Click **Save Decorator**.

```json
{
  "type": "object",
  "properties": {
    "zone_id": {
      "type": "string",
      "description": "The DNS zone identifier returned by the zone lookup tool. Don't use the zone name here."
    }
  }
}
```

Unlike `enum` or `required`, a property's `description` doesn't restrict or validate what the agent sends. It only shapes how the agent interprets the field, so pair it with the techniques above when you need enforcement rather than guidance.

> **Note**
>
> This is the `description` keyword on an individual property inside the schema. It isn't the same as the **Override Tool Description** field, which describes what the tool as a whole does.

## Troubleshoot a schema change

**The agent still sends a field you removed.** Saving creates the decorator but doesn't apply it. Confirm the decorator you saved is the active one for that tool, and that you haven't assigned a different decorator since.

**The agent sends a value outside your enum list.** Confirm you defined the `enum` array on the property itself rather than at the root of the schema, and that you saved the decorator after adding it.

**You want to undo a change you already saved.** You can't change a saved decorator, so reassign the earlier decorator if one exists, or clone the current one and correct the copy.

## Related information

* [Creating your first schema](https://json-schema.org/learn/getting-started-step-by-step)
* [Schema decorators](/itential-platform/flowai/agent-projects/agent-builder#schema-decorators)
* [Promote decorators](/itential-platform/flowai/agent-projects/export-decorators)

> Set default values, restrict allowed values, limit which fields an agent can use, and add clarifying descriptions in a decorator's JSON schema.