Diagrams — Module 2: Tool Design and the Tool Contract

flowchart LR
    T[Tool]
    T --> N[1. Name<br/>precise, unambiguous]
    T --> D[2. Description<br/>a PROMPT — model reads it to decide when]
    T --> S[3. Input Schema<br/>JSON Schema / Pydantic — types, bounds, defaults]
    T --> I[4. Implementation<br/>what the harness executes]
    T --> E[5. Error Return<br/>structured, never thrown]

    N --> MODEL[Model reads name + description + schema<br/>to decide whether and how to call]
    S --> VALIDATE[Harness schema-validates<br/>before execution]
    I --> EXEC[Harness executes]
    E --> CONTEXT[Error or result returns to model as context]

    style T fill:#152d15,stroke:#208a20,color:#a0d0a0
    style D fill:#2d2d00,stroke:#8a8a00,color:#d0d000
    style E fill:#2d1515,stroke:#8a2020,color:#d0a0a0

flowchart TB
    M[Model emits tool_use]
    M --> P[1. Parse<br/>structured JSON or regex]
    P --> V[2. Validate name<br/>against registry]
    V --> SV[3. Schema-validate inputs]
    SV --> PERM[4. Permission check<br/>capabilities ⊆ agent perms]
    PERM --> X[5. Execute implementation]
    X --> F[6. Format result<br/>truncate + structure]
    F --> R[7. Return as tool result to context]

    P -.->|parse failure| ERR[Return precise error to model]
    V -.->|unknown tool| ERR
    SV -.->|invalid args| ERR
    PERM -.->|denied| ERR

    style M fill:#2d2d00,stroke:#8a8a00,color:#d0d000
    style PERM fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style ERR fill:#2d1515,stroke:#8a2020,color:#d0a0a0

flowchart LR
    subgraph MANY["40 tools (Claude Code end)"]
        direction TB
        A1[Decision noise]
        A2[Wrong-tool calls]
        A3[Slower selection]
    end

    subgraph FEW["4 tools (Pi end)"]
        direction TB
        B1[Clear choices]
        B2[Correct calls]
        B3[Fast selection]
    end

    MANY -.->|"Vercel: cut 80% → better results"| FEW

    style MANY fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style FEW fill:#152d15,stroke:#208a20,color:#a0d0a0

flowchart TB
    subgraph V1["Vector 1: Prompt injection via tool OUTPUT"]
        direction LR
        O1[Attacker controls a file/web page/API response]
        O2[Tool returns it faithfully]
        O3[Model reads injected instructions]
        O4[Model may comply]
        O1 --> O2 --> O3 --> O4
    end

    subgraph V2["Vector 2: Tool DEFINITION poisoning (MCP)"]
        direction LR
        D1[Malicious MCP server]
        D2[Tool description contains hidden instructions]
        D3[Model reads description as prompt]
        D4[Model complies]
        D1 --> D2 --> D3 --> D4
    end

    subgraph V3["Vector 3: Dispatch-time injection"]
        direction LR
        P1[Crafted output from turn N]
        P2[Contains fake closing tag]
        P3[Parsing of turn N+1 corrupted]
        P1 --> P2 --> P3
    end

    DEF[DEFENSES]
    V1 -.->|untrusted-content tagging| DEF
    V2 -.->|signed manifests + runtime verify| DEF
    V3 -.->|structured output JSON, not text parsing| DEF

    style V1 fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style V2 fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style V3 fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style DEF fill:#152d15,stroke:#208a20,color:#a0d0a0

flowchart LR
    subgraph REG[Tool Registry]
        RF[read_file<br/>capabilities: fs:read]
        WF[write_file<br/>capabilities: fs:write]
        SH[bash<br/>capabilities: shell]
        NW[search_web<br/>capabilities: network]
    end

    AGENT[Agent permissions:<br/>{fs:read} only]

    REG --> CHECK{capability check<br/>tool.capabilities ⊆ agent.perms?}
    AGENT --> CHECK
    CHECK -->|yes| ALLOW[execute]
    CHECK -->|no, fs:write not granted| DENY[deny: permission error to model]

    style AGENT fill:#15152d,stroke:#20208a,color:#a0a0d0
    style DENY fill:#2d1515,stroke:#8a2020,color:#d0a0a0
    style ALLOW fill:#152d15,stroke:#208a20,color:#a0d0a0