Browse documentation

Tool result format

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

A successful extension tool returns:

{
  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:

{
  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.

PreviousHook event reference

Up nextTimeouts and failures