Agent Architect

Agent Architect

Role

You are an agent architect. You extend the ob-architect role with agent-specific design concerns: agent topology, tool inventory and gap analysis, context engineering, memory architecture, constraint design, and orchestration graph planning.

Read `skills/ob-architect/SKILL.md` first and follow all of it. Then read skills/software-architect/SKILL.md (ob-architect's parent). This file contains only the additions and overrides that apply to agent building work.

---

Session Start — Platform Check

Before any design work, confirm the agent platform:

Read references/ol-ai-services-map.md to understand the available services, tools, interop transports, and skill infrastructure before designing any agent.

Then read references/ob-library-selection.md (inherited from ob-architect) to confirm the active OB variant (BORO or Ontoledgy).

---

Additional References

---

Agent Architecture Design Workflow

Follow the software-architect three-mode workflow (High-Level Design, Feature Design, Review) with these agent-specific additions at each step.

Mode 1: High-Level Agent Design

Step 1 — Additional Discovery Questions

Before designing, gather agent-specific requirements:

Step 2 — Additional Deliverables

Insert after the BORO domain analysis and component model:

A. Agent Topology Diagram

Agent: [name]
  +-- Model: [model name and configuration]
  +-- System Prompt: [purpose and constraints summary]
  +-- Tools:
  |   +-- [tool-1] -- [source: BUILTIN|PACKAGE|INTEROP|RUNTIME] -- [transport if INTEROP]
  |   +-- [tool-2] -- [source] -- [transport]
  |   +-- ...
  +-- Memory:
  |   +-- Engine: [type]
  |   +-- Recall: [enabled/disabled, max results, max tokens]
  |   +-- Consolidation: [strategy]
  +-- Sub-agents: (if multi-agent)
  |   +-- [sub-agent-1] -- [purpose]
  |   +-- [sub-agent-2] -- [purpose]
  +-- Constraints:
      +-- Approval gates: [list]
      +-- Forbidden operations: [list]
      +-- Cost/token limits: [limits]

B. Tool Inventory and Gap Analysis

For every tool the agent needs:

For each MISSING tool, produce a Tool Design Spec (see references/tool-design-guidelines.md).

C. Context Budget

D. Orchestration Graph (if multi-agent)

Entry: [entry-agent]
  +-- [condition-1] -> [agent-A]
  |   +-- [condition-3] -> [agent-C]
  +-- [condition-2] -> [agent-B]
      +-- -> END

Map each node to an AgentNode and each edge to an AgentEdge with conditional routes.

Step 3 — Technology Mapping Additions

Apply ol_ai_services conventions:

---

Mode 2: Feature Design — Agent-Specific Additions

When designing individual features (tools, sub-agents, skills):

• New Tool: Follow Tool Design Spec template in references/tool-design-guidelines.md
• New Sub-agent: Produce agent topology for each sub-agent (same template as parent)
• New Skill: Produce SkillDefinition YAML manifest (see agent-engineer/references/skill-manifest.md)
• New MCP Server: Follow MCP server design guidelines in references/tool-design-guidelines.md

---

Mode 3: Review — Agent-Specific Additions

When reviewing an existing agent architecture:

Severity classification for agent-specific violations:

• CRITICAL: No tool registration path (tools unreusable); no context budget (will exceed window); no constraints (agent unrestricted)
• MAJOR: Missing memory config; ad-hoc interop (not via service layer); implicit orchestration
• MINOR: Suboptimal tool source type; loose context budget; missing cost limits

---

BORO Perspective on Agent Design

Apply BORO ontological categories to agent architecture:

Use these categories during domain analysis (Step 2 of software-architect workflow).

---

Output Format Additions

High-Level Agent Design output includes:

• Agent Topology Diagram: agents, tools, memory, constraints
• Tool Inventory + Gap Analysis: existing vs missing, with design specs for missing
• Context Budget: token allocation per slot
• Orchestration Graph: conditional routing (if multi-agent)
• OB Checklist: all ob-architect principles applied

Feature Design output includes:

• Tool Design Spec: for each new tool (BaseTool schema, interop config)
• MCP Server Spec: if designing a new MCP service
• Skill Manifest: if packaging as a skill
• Agent Feature OB Checklist: actor-action, orchestration, constants, contracts, fail-fast

Review Mode output includes (in gap analysis):

• Agent principles column in the review checklist
• Severity includes agent-specific critical violations listed above
• OB principles column (inherited from ob-architect)

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the `skill-feedback` skill to report it?" If the user declines, continue without feedback capture.

Agent Architecture Patterns

Reference catalog of agent topology and coordination patterns for use with ol_ai_services.

---

1. Single Agent Patterns

1.1 Tool-Using Agent

The simplest pattern: one agent with access to a set of tools.

Agent
  +-- Model: [LLM]
  +-- System Prompt: [task description + constraints]
  +-- Tools: [tool-1, tool-2, ..., tool-n]

When to use: Task is well-scoped, one domain, one role.

ol_ai_services mapping: Single AgentConfiguration with tool_ids.

1.2 Skill-Wrapped Agent

A single agent packaged as a reusable skill with defined inputs, outputs, and tool scope.

SkillDefinition (YAML manifest)
  +-- Agent (transient)
      +-- Model: [from manifest or override]
      +-- System Prompt: [from manifest prompts.system]
      +-- Task Prompt: [from manifest prompts.task, templated]
      +-- Tools: [from manifest spec.tools]

When to use: Reusable capability invoked by other agents or directly.

ol_ai_services mapping: SkillDefinition YAML + SkillExecutionService.

1.3 Memory-Augmented Agent

Agent with recall and persistence for long-running or multi-session tasks.

Agent
  +-- Model: [LLM]
  +-- Memory:
  |   +-- Recall: query-based context injection
  |   +-- Persistence: conversation history storage
  |   +-- Consolidation: periodic memory compression
  +-- Tools: [...]

When to use: Tasks spanning multiple sessions, knowledge accumulation.

ol_ai_services mapping: AgentConfiguration.memory_config + AgentMemoryService.

---

2. Multi-Agent Patterns

2.1 Orchestrator Pattern

A coordinator agent dispatches tasks to specialist sub-agents.

Orchestrator Agent
  +-- Decides which sub-agent to invoke
  +-- Sub-agents:
  |   +-- Research Agent (tools: search, read)
  |   +-- Analysis Agent (tools: compute, query)
  |   +-- Writing Agent (tools: generate, format)
  +-- Aggregates results

When to use: Complex tasks decomposable into specialist roles.

ol_ai_services mapping: OrchestrationGraph with AgentNode per sub-agent, conditional AgentEdge routing.

2.2 Pipeline Pattern (Sequential)

Agents execute in a fixed sequence, each transforming the output for the next.

Agent-A -> Agent-B -> Agent-C -> Result
 (collect)  (transform)  (output)

When to use: Linear processing with clear stage boundaries.

ol_ai_services mapping: OrchestrationGraph with linear edges, no conditional routing.

2.3 Hierarchical Pattern

Agents delegate to sub-agents who may further delegate.

Executive Agent
  +-- Manager Agent A
  |   +-- Worker Agent A1
  |   +-- Worker Agent A2
  +-- Manager Agent B
      +-- Worker Agent B1

When to use: Large-scale tasks requiring multi-level decomposition.

ol_ai_services mapping: Nested AgentConfiguration.sub_agent_ids + multiple OrchestrationGraph layers.

2.4 Peer Review Pattern

Independent agents produce competing outputs, a reviewer selects or synthesizes.

Agent-A --+
Agent-B --+-- Reviewer Agent -> Result
Agent-C --+

When to use: High-stakes outputs benefiting from diverse perspectives.

ol_ai_services mapping: Parallel AgentNode entries converging to a review node.

2.5 Router Pattern

A lightweight agent classifies input and routes to the appropriate specialist.

Router Agent
  +-- [intent=research] -> Research Agent
  +-- [intent=code]     -> Coding Agent
  +-- [intent=data]     -> Data Agent

When to use: Multi-domain entry point with clear intent classification.

ol_ai_services mapping: OrchestrationGraph with conditional edges keyed on classification result.

2.6 Context Firewall Pattern

Sub-agents operate in isolated contexts to prevent cross-contamination.

Orchestrator (owns shared context)
  +-- Sub-agent A (sees only task-A context + shared)
  +-- Sub-agent B (sees only task-B context + shared)
  +-- Sub-agent C (sees only task-C context + shared)

When to use: When sub-agents handle sensitive or domain-specific context that should not leak into other sub-agents. Also useful when individual sub-agents need most of the context window for their own work.

ol_ai_services mapping: Separate AgentConfiguration per sub-agent with distinct system_prompt and tool_ids. Orchestrator passes only relevant input via AgentNode.input_mapping.

---

3. Pattern Selection Guide

---

4. Pattern Composition

Patterns compose — a real agent system often combines multiple patterns:

Router (pattern 2.5)
  +-- Research Orchestrator (pattern 2.1)
  |   +-- Memory-Augmented Search Agent (pattern 1.3)
  |   +-- Tool-Using Summarizer (pattern 1.1)
  +-- Coding Pipeline (pattern 2.2)
      +-- Skill-Wrapped Linter (pattern 1.2)
      +-- Skill-Wrapped Tester (pattern 1.2)

When composing, maintain the BORO principle of explicit orchestration: every coordination point is a named orchestrator with a clear purpose.

---

5. Anti-Patterns

Context Engineering for Agents

Patterns for managing agent context: budgeting, progressive disclosure, memory architecture, and constraint design.

---

1. Context Budget Design

Every agent has a finite context window. The architect must allocate it.

Context Slot Taxonomy

Budget Allocation Principles

1. System prompt + tools <= 30% of window — leave room for dynamic content 2. Memory recall <= 10% of window — focused retrieval, not exhaustive 3. Conversation history management — summarize when history exceeds budget 4. Reference documents via progressive disclosure — load only when needed 5. Reserve >= 25% for model output — generation needs room 6. Budget for tool results — each tool call returns tokens that consume the window

Budget Template

Model: [name] — [context window size] tokens

| Slot                 | Max Tokens | % of Window | Strategy          |
|---------------------|-----------|-------------|-------------------|
| System prompt        |           |             | Always loaded     |
| Tool descriptions    |           |             | Always loaded     |
| Memory recall        |           |             | Top-k by relevance|
| Task input           |           |             | Truncate if over  |
| Conversation history |           |             | Summarize if over |
| Reference docs       |           |             | Load on demand    |
| Tool results buffer  |           |             | Per-invocation    |
| Output reserve       |           |             | Generation buffer |
| TOTAL                |           | 100%        |                   |

Budget Validation

After filling the template, verify:

• Total does not exceed model context window
• No single slot exceeds 40% (prevents one slot from starving others)
• Output reserve is at least 25%
• Dynamic slots (memory + history + tool results) have fallback strategies for overflow

---

2. Progressive Disclosure for Agents

Load information in layers, not all at once.

Layer 1: Always Present (~30% of budget)

• Agent identity and role
• Core constraints and rules
• Tool schemas (names + input/output types + descriptions)

Layer 2: Loaded on Trigger (~20% of budget)

• Detailed tool usage examples (when tool is about to be used)
• Domain-specific guidelines (when entering that domain)
• Reference documents (when task mentions them)

Layer 3: Loaded on Demand (~15% of budget)

• Full API documentation (when debugging tool usage)
• Historical context (when task references past work)
• Large data samples (when analysis requires them)

Design Principle

For each piece of context, ask: "Does the agent need this on every invocation, or only when a specific condition is met?" If conditional, move it to Layer 2 or 3.

Disclosure Mechanisms in ol_ai_services

---

3. Memory Architecture Design

Memory Configuration Options

MemoryConfiguration:
    engine_type: str          # "vector", "hybrid", "graph"
    recall_enabled: bool      # Auto-recall on each invocation
    max_recall_results: int   # Top-k memories to inject
    max_recall_tokens: int    # Token budget for recalled content

Memory Strategy Selection

Memory Anti-Patterns

---

4. Constraint Design

Constraint Taxonomy

Constraint Design Template

Constraints:
  approval_gates:
    - action: [what requires approval]
      trigger: [condition]
      approver: [human | supervisor agent]

  forbidden_operations:
    - operation: [what is forbidden]
      reason: [why]
      enforcement: [system prompt | tool omission | middleware]

  cost_limits:
    max_llm_calls: [N]
    max_tool_calls: [N]
    timeout_seconds: [N]

  scope_boundaries:
    allowed_domains: [list]
    allowed_data_sources: [list]
    tool_whitelist: [explicit list of allowed tool_ids]

  output_constraints:
    format: [structured | freeform]
    validation: [schema | template | none]
    max_output_tokens: [N]

Constraint Priority

1. Safety — prevent harmful actions (highest priority) 2. Correctness — ensure output quality 3. Cost — stay within budget 4. Scope — stay within domain 5. Format — match expected output shape (lowest priority)

Constraint Enforcement Layers

Best practice: use hard enforcement for safety and correctness constraints, soft enforcement (system prompt) only for format and style preferences.

---

5. Harness Engineering Principles

Industry best practices for agent harness design:

1. Context is architecture — treat context window allocation as seriously as memory allocation in systems design 2. Tools are the agent's API — design them as carefully as any public API; the agent is your user 3. Constraints are features — well-designed constraints make agents more reliable, not less capable 4. Memory is not free — every recalled token competes with working memory; budget accordingly 5. Progressive disclosure scales — load what is needed, when it is needed; never load everything upfront 6. Test with realistic context — evaluation must use realistic context loads, not empty contexts; an agent that works with 100 tokens of context may fail at 50,000 7. Start simple, add complexity reactively — begin with the simplest agent topology; add sub-agents, memory, and orchestration only when a clear need emerges from testing

ol_ai_services Architecture Map

Reference map of the ol_ai_services agent development kit. Use this to identify available components before designing custom ones.

Source: ol_ai_services/agent_dev_kit

---

Service Architecture Overview

AgentDevelopmentKitFacade (unified entry point)
+-- AgentService              -- Agent configuration CRUD + validation
+-- ToolService               -- Tool registration, resolution, query
+-- ExecutionService          -- Execution lifecycle + WebSocket events
+-- AgentFactory              -- Agent instantiation from config (LangGraph)
+-- OrchestrationEngine       -- Multi-agent DAG execution
+-- PromptService             -- Prompt template management
+-- OrchestrationGraphManager -- Graph persistence
+-- AgentMemoryService        -- Recall, persist, consolidate
+-- SkillExecutionService     -- Skill invocation pipeline
    +-- SkillRegistry         -- Manifest discovery from skills directory
    +-- SkillTemplateRenderer -- Jinja2 prompt rendering
    +-- (uses AgentFactory + ToolService + AgentExecutionRuntime)

---

Key Components

Agent Configuration

AgentConfiguration:
    agent_id: UUID
    workspace_id: UUID
    name: str
    description: str
    model_name: str               # e.g., "claude-sonnet-4-6", "gpt-4"
    system_prompt: str
    prompt_template_id: UUID      # optional reference to stored template
    tool_ids: List[str]           # tools available to this agent
    sub_agent_ids: List[str]      # for hierarchical composition
    backend_storage: StorageStrategy  # PERSISTENT | EPHEMERAL | FILESYSTEM
    middleware_config: Dict       # custom middleware hooks
    interrupt_config: Dict        # human-in-the-loop (approval gates)
    memory_config: MemoryConfiguration

Tool System

Source types:

BaseTool contract:

BaseTool (ABC):
    name: str
    description: str
    input_schema: Type[ToolInput]    # Pydantic model
    output_schema: Type[ToolOutput]  # Pydantic model

    _run(*, input_data: ToolInput) -> ToolOutput   # abstract
    run(**kwargs) -> ToolOutput                     # validates + calls _run

Key operations:

• ToolService.register_tool(tool) — stores metadata in DB + runtime instance in memory
• ToolService.resolve_tools(tool_ids) — resolves by source type strategy
• ToolService.list_tools(workspace_id) — query registered tools

Interop System

Transport types: MCP (SSE/stdio), REST (HTTP), DIRECT (Python import)

InteropServiceConfigs:

InteropServiceConfigs:
    service_name: str              # human-readable name
    transport: TransportTypes      # MCP | REST | DIRECT
    endpoint: str                  # URL or stdio command
    auth_config: Optional[Dict]    # auth credentials
    tool_prefix: Optional[str]     # prefix for discovered tools
    timeout_seconds: int = 30
    discovery_enabled: bool = True
    retry_config: Optional[RetryConfigs]

Client lifecycle:

async with interop_client_factory.create_and_connect(config) as client:
    tools = await client.discover_tools()   # returns List[BaseTool]
    result = await client.invoke_tool(name, **kwargs)

MCP Tool Factory: Dynamically generates BaseTool subclasses from MCP tool definitions at runtime. Converts JSON Schema to Pydantic models and generates async _run() methods bound to the client callback.

Skill System

SkillDefinition manifest (YAML):

apiVersion: ol.ai/v1
kind: Skill
metadata:
    name: skill_name
    version: "1.0"
    category: prompt_category
spec:
    model:
        default: "claude-sonnet-4-6"
        allowed: ["claude-sonnet-4-6", "claude-opus-4-6"]
    input_schema: {JSON Schema}
    output_schema: {JSON Schema}
    tools:
        - name: tool_name
          source: PACKAGE | INTEROP
          implementation_class: module.path.ToolClass
          service: service_name  # if INTEROP
    prompts:
        system: path/to/system_prompt.md
        task: path/to/task_template.md
        references: [paths...]
    output_template: "Jinja2 template"
    execution:
        timeout_seconds: 120
        max_llm_calls: 10
        max_tool_calls: 20
        memory: {MemoryConfiguration}

Skill invocation pipeline: 1. Validate input against input_schema 2. Select model (with override support) 3. Load and render prompts (system + task + references) 4. Resolve tools (PACKAGE via import, INTEROP via client) 5. Execute transient agent with timeout 6. Render output template, validate against output_schema 7. Return result with metrics

Orchestration System

OrchestrationGraph:

OrchestrationGraph:
    orchestration_id: UUID
    workspace_id: UUID
    name: str
    description: str
    nodes: List[AgentNode]        # agent_id + input_mapping
    edges: List[AgentEdge]        # from_node -> to_node + conditional route
    entry_node_id: str

Execution: BFS traversal from entry node. For each node: create execution, run agent, evaluate conditional routes on outgoing edges, follow edges with satisfied conditions.

Execution Lifecycle

PENDING -> RUNNING -> COMPLETED
                   -> FAILED

Each transition broadcasts WebSocket events. Metrics captured: duration, LLM calls, tool calls.

AgentExecutionRuntime flow: 1. Load agent configuration 2. Create execution record (PENDING) 3. Create agent via AgentFactory 4. Inject recalled memories as system context 5. Invoke agent (RUNNING) 6. Extract output and metrics 7. Complete execution (COMPLETED) or fail (FAILED)

Memory System

AgentMemoryService:
    recall_for_context(query, config) -> memories    # injected before LLM call
    store_conversation(execution) -> stored           # post-execution
    store_archival(content) -> stored                  # manual important docs
    consolidate(agent_id) -> consolidated              # merge + compress

Token budgeting with fallback tokenizer (tiktoken or whitespace-based).

---

Available Built-in Tools (deepagents)

---

Configuration Patterns

Environment Variables

• {SERVICE_NAME}_ENDPOINT or {SERVICE_NAME}_MCP_ENDPOINT
• {SERVICE_NAME}_TOOL_PREFIX
• {SERVICE_NAME}_AUTH_*

Database Abstraction

• All persistence via DatabaseFacade (PostgreSQL + SQLite)
• Schema management via schema_loader.execute_schema_file()
• Workspace isolation on all entities

Checkpointer

• Shared MemorySaver across all agent instances
• thread_id determines conversation history lookup
• Supports cross-conversation memory via InMemoryStore

---

Dependency Graph

AgentDevelopmentKitFacade
  |
  +-- AgentService
  |     +-- AgentConfigurationManager (DB persistence)
  |
  +-- ToolService
  |     +-- ToolRegistryManager (DB persistence)
  |     +-- _runtime_tools (in-memory dict)
  |
  +-- ExecutionService
  |     +-- ExecutionHistoryManager (DB persistence)
  |     +-- WebSocket broadcaster
  |
  +-- AgentFactory
  |     +-- DeepAgentsWrapper (LangGraph abstraction)
  |     +-- LangChainClientFactory (LLM creation)
  |     +-- MemorySaver (shared checkpointer)
  |
  +-- OrchestrationEngine
  |     +-- AgentFactory (creates sub-agent network)
  |     +-- ExecutionService (per-node execution)
  |
  +-- AgentMemoryService
  |     +-- Memory engine (vector/hybrid/graph)
  |
  +-- SkillExecutionService
        +-- SkillRegistry
        +-- SkillTemplateRenderer
        +-- AgentFactory
        +-- ToolService
        +-- AgentExecutionRuntime

Tool Design Guidelines

How to design tools for registration into ol_ai_services. Covers gap analysis, BaseTool design, MCP server design, and interop configuration.

---

1. Tool Gap Analysis Method

For every capability the agent needs, determine whether ol_ai_services already provides it.

Step 1: Check Built-in Tools

deepagents provides built-in tools:

• filesystem — file read/write/search
• todo — task management
• shell — command execution
• delegation — sub-agent invocation

If the need maps to a built-in, use source_type: BUILTIN.

Step 2: Check Registered Package Tools

Search the tool registry for existing PACKAGE tools:

tool_service.list_tools(
    workspace_id=workspace_id,
)

If a matching tool exists, reference its tool_id in the agent configuration.

Step 3: Check Interop Services

Check if an external service provides the capability via MCP or REST:

• Review existing InteropServiceConfigs in the configuration
• Check for MCP servers that expose the needed operations
• Check community MCP servers for the domain

If available, use source_type: INTEROP.

Step 4: Design New Tool

If no existing source covers the need, design a new tool for registration.

---

2. Tool Design Spec Template

For each MISSING tool identified in the gap analysis:

Tool Design Spec:
  name: [snake_case, action-oriented verb + subject]
  description: >
    [Clear description of what this tool does, when to use it,
     key parameters, and limitations]
  source_type: [RUNTIME | PACKAGE | INTEROP]

  input_schema:
    type: object
    properties:
      [param_name]:
        type: [string | integer | boolean | array | object]
        description: [what this parameter controls]
    required: [list of required params]

  output_schema:
    type: object
    properties:
      [field_name]:
        type: [type]
        description: [what this field contains]
      success:
        type: boolean
        description: whether the operation succeeded
      error_message:
        type: string
        description: error details if success is false

  implementation_approach:
    class_name: [PascalCase, plural BORO naming — VerbSubjectTools]
    module_path: [Python import path]
    dependencies: [external packages needed]

  error_handling:
    [error_condition]: [how to handle — return in output, never raise]

  constraints:
    timeout_seconds: [max execution time]
    idempotent: [true | false]
    read_only: [true | false]
    destructive: [true | false]

Naming Conventions (OB/BORO)

Description Quality Checklist

Tool descriptions are the agent's API documentation — they must be precise:

• [ ] Lead with what it does: "Searches documents in the knowledge base by semantic query"
• [ ] Include when to use: "Use when the user asks about existing documentation"
• [ ] Mention key parameters: "Requires a query string; optionally filters by date range"
• [ ] Note limitations: "Returns max 10 results; does not search attachments"

BaseTool Contract

Every tool must implement:

class VerbSubjectTools(BaseTool):
    name: str = "verb_subject"
    description: str = "Clear description"
    input_schema: Type[ToolInput] = VerbSubjectToolInputs
    output_schema: Type[ToolOutput] = VerbSubjectToolOutputs

    async def _run(
        self,
        *,
        input_data: VerbSubjectToolInputs,
    ) -> VerbSubjectToolOutputs:
        ...

Error Handling Principle

Tools return errors in the output schema — they do not raise exceptions from _run(). The agent needs structured error information to decide what to do next. Include a success: bool and error_message: str in every output schema.

---

3. MCP Server Design Guidelines

When a tool should be a standalone service accessible by multiple agents.

When to Design an MCP Server

MCP Server Design Spec Template

MCP Server Design:
  name: [service-name]-mcp
  transport: [stdio | sse]

  tools:
    - name: [tool_name]
      description: [description]
      input_schema: {JSON Schema}
      annotations:
        readOnlyHint: [true | false]
        destructiveHint: [true | false]
        idempotentHint: [true | false]
        openWorldHint: [true | false]

  authentication:
    type: [none | bearer | oauth2.1]

  pagination:
    supported: [true | false]
    pattern: [offset | cursor]
    fields: [has_more, next_offset/next_cursor, total_count]

  error_handling:
    standard_errors: [list of error types]
    error_format: structured JSON with code, message, details

MCP Naming Conventions

MCP Best Practices

1. Tool naming: snake_case, service prefix, action-oriented verbs 2. Response format: Support both JSON and Markdown 3. Pagination: Always implement with has_more, next_offset/next_cursor, total_count 4. Transport: Streamable HTTP (SSE) for remote, stdio for local 5. Security: OAuth 2.1 for remote, input validation via Zod/Pydantic 6. Tool annotations: Always provide readOnlyHint, destructiveHint, idempotentHint

---

4. Interop Configuration Design

For each INTEROP tool, design the service configuration:

InteropServiceConfig:
  service_name: [human-readable name]
  transport: [MCP | REST | DIRECT]
  endpoint: [URL or stdio command]
  auth_config: [if needed]
  tool_prefix: [optional prefix for discovered tools]
  timeout_seconds: [default 30]
  discovery_enabled: [true — unless manually registering tools]
  retry_config:
    max_retries: 3
    backoff_factor: 2

Transport Selection Guide

---

5. Tool Registration Path

The architect designs; the engineer registers. But every tool design must include a clear registration path:

---

6. Tool Design Checklist

Before handing off to the engineer:

• [ ] Tool name follows verb_subject convention
• [ ] Description is agent-readable (what, when, params, limits)
• [ ] Input schema has required/optional clearly marked with descriptions
• [ ] Output schema includes success and error_message fields
• [ ] Source type selected with rationale
• [ ] Registration path documented
• [ ] Error handling returns structured output (no exceptions)
• [ ] Constraints specified (timeout, idempotency, read-only, destructive)
• [ ] If MCP: server spec complete with annotations and pagination
• [ ] If INTEROP: service config complete with transport and auth