# Tool Renderer Contract

> Design and review structured tool-result rendering. Use when rendering tool calls, tool messages, structured tool outputs, status cards, fallback JSON/text displays, parser boundaries, display status mappings, or unknown tool results.

- **Type:** Skill
- **Install:** `agentstack add skill-hsienw-ai-agent-engineering-playbook-tool-renderer-contract`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HsienW](https://agentstack.voostack.com/s/hsienw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HsienW](https://github.com/HsienW)
- **Source:** https://github.com/HsienW/ai-agent-engineering-playbook/tree/master/skills-contract-boundaries/tool-renderer-contract

## Install

```sh
agentstack add skill-hsienw-ai-agent-engineering-playbook-tool-renderer-contract
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tool Renderer Contract

## Skill Interface

- Name: tool-renderer-contract.
- Description: Design and review structured tool-result rendering for tool calls, tool messages, structured tool outputs, status cards, fallback JSON or text displays, parser boundaries, display status mappings, and unknown tool results.
- Parameters: Tool result schema, raw message content, parser boundary, display status mapping, known specialized renderers, fallback rendering behavior, sensitive field policy, and verification cases.
- Instructions: Use this skill when rendering tool output in UI. Parse raw output as untrusted data, validate minimum structured fields, map status through a closed display union, provide safe fallbacks for unknown tools, and verify malformed, future-version, and sensitive-data cases.

Tool rendering should be schema-driven and resilient to unknown tools. The UI
must not trust raw tool output as display-ready data.

## Layers

1. Message container: owns message grouping and association between tool call
   metadata and tool output.
2. Generic tool renderer: parses common metadata, displays status, and chooses a
   specialized renderer when one is available.
3. Specialized renderer: renders a known tool result schema.
4. Fallback renderer: safely displays unknown JSON, text, or parse failures.

## Structured Result Shape

Use a generic shape that can be specialized:

```ts
type ToolResult = {
  schemaVersion: string;
  tool: string;
  status: TStatus;
  data?: TData;
  summary?: string;
  errorCode?: string;
};
```

The frontend parser should accept `unknown` or raw message content, validate the
minimum fields, and return a typed result or `undefined`.

## Status Mapping

Map tool status through a closed display status union:

```ts
type ToolDisplayStatus =
  | 'running'
  | 'success'
  | 'needs_input'
  | 'not_found'
  | 'denied'
  | 'error'
  | 'timeout'
  | 'cancelled'
  | 'unknown';
```

Use a single `Record` for labels, icons,
colors, and ARIA text. Do not scatter status rendering across component
branches.

## Safety Rules

- Treat tool output as untrusted.
- Never render raw HTML from tool output unless sanitized by a trusted policy.
- Never expose stack traces, credentials, provider secrets, or raw internal
  payloads.
- Do not infer status from user-visible text.
- Do not hardcode one tool result as the only rendering path.
- Unknown tools must have a safe fallback.

## Parser Rules

- Validate `schemaVersion`, `tool`, and `status`.
- Preserve unknown fields for diagnostics only when safe.
- Be forward compatible with unknown minor schema versions.
- Provide unknown-status fallback.
- Keep type assertions behind runtime checks.

## Verification

Test known structured results, unknown tool results, malformed JSON, plain text
output, unknown status, future schema versions, error envelope rendering, and
sensitive field redaction.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HsienW](https://github.com/HsienW)
- **Source:** [HsienW/ai-agent-engineering-playbook](https://github.com/HsienW/ai-agent-engineering-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hsienw-ai-agent-engineering-playbook-tool-renderer-contract
- Seller: https://agentstack.voostack.com/s/hsienw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.