Errors and Gotchas

Server/client boundaries

• Do not import agents/server, tools/server, chat/server, or mcp/server from client components.
• Client tool renderers should use type-only imports from server tools.
• Keep actual tool execution on the server.

Tool design

• Do not put resolver metadata inside defineTool().
• Put permissions, confirmation, audit, and UI metadata in resolveAgentTool().
• Add read/search tools before write tools.
• Confirmation metadata is not a substitute for good agent instructions.

Agent behavior

• Avoid one giant assistant with every tool.
• Use specialist agents for bounded domains.
• Do not let agents mutate business records without explicit user intent.
• Make duplicate checks and lookup steps part of specialist instructions.

Chat UI

• Pass status to both ChatThread and ChatComposer.
• ChatComposer keeps typing available while streaming, but blocks submit until status === "ready".
• Unknown tools fall back to ToolCallCard, but important tools should get named renderers.

Streaming

• Always forward abort signals from the request/RPC layer.
• Keep server handlers focused on transport; put domain behavior in agents and tools.
• If a stream fails, inspect provider errors and tool exceptions before changing the UI.

Heuristic

If a bug feels behavioral, inspect the agent instructions and tool descriptions first.

If a bug feels data-related, inspect the tool implementation and schemas.

If a bug feels visual, inspect the client tool renderer and chat composition.