# Tool result format

Return model-visible content and optional structured details from a hosted tool.

A successful extension tool returns:

```js
{
  content: [
    {
      type: 'text',
      text: 'Model-visible result',
    },
  ],
  details: {
    optional: 'structured metadata',
  },
}
```

## Fields

| Field     | Requirement                                                    |
| --------- | -------------------------------------------------------------- |
| `content` | Required array of text items for extension tool execution      |
| `details` | Optional JSON-safe metadata used by diagnostics or later hooks |

Keep `content` concise because it enters the model conversation. Keep `details` bounded and free of secrets.

## Tool-result hook patches

A `tool_result` lifecycle handler can return any of:

```js
{
  content,
  details,
  isError,
  terminate,
}
```

Only returned fields are changed. Later handlers receive the accumulated result. `terminate: true` asks the harness to end the current agent loop after the tool result.

## Errors

Throw an `Error` when the tool cannot produce a valid result. Use a safe message suitable for sanitized runtime diagnostics. Never include tokens, provider payloads, or credentials in the message.