Minimal Artifact Metadata

Lean Artifact Metadata & Summary Density Protocol

Overview

When agents create or update living markdown artifacts (implementation_plan.md, walkthrough.md, architecture_rfc.md), tools require an ArtifactMetadata dictionary payload.

Unoptimized agents generate 150 to 300 words of conversational meta-commentary inside the Summary field ("In this artifact, I have thoroughly documented all of the comprehensive steps that we are going to take during the implementation phase of our refactoring project...").

Because artifact metadata is passed in tool arguments and re-indexed into agent context, verbose summaries burn hundreds of tokens per artifact mutation turn.

The Lean Artifact Metadata Protocol enforces dense 1-to-2 sentence summary definitions focusing strictly on content purpose while eliminating rhetorical padding.

Verbose Metadata vs. Lean High-Density Schema

┌─────────────────────────────────────────────────────────────┐
│                 Artifact Metadata Token Impact              │
│                                                             │
│  Verbose Narrative Metadata (185 Tokens):                   │
│  "ArtifactMetadata": {                                      │
│    "Summary": "This document represents a detailed and      │
│     comprehensive architectural overview of the system.     │
│     It explains the database schema changes, the new API    │
│     endpoints, and the testing strategy that will be used   │
│     to ensure zero regressions across the service.",        │
│    "UserFacing": true,                                      │
│    "RequestFeedback": true                                  │
│  }                                                          │
│                                                             │
│  Lean High-Density Metadata (28 Tokens - 84.8% Cut!):       │
│  "ArtifactMetadata": {                                      │
│    "Summary": "Architecture RFC: Auth service migration to  │
│     Redis token revocation with zero-downtime schema.",     │
│    "UserFacing": true,                                      │
│    "RequestFeedback": true                                  │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘

The 3 Rules of Lean Artifact Metadata

1. Zero Self-Referential Preamble

Never write "This artifact contains...", "In this document...", or "I have created a...". State the topic and deliverable directly.

2. Focus on Content Scope, Not Action History

Summarize what the document is, not what you did to write it:

• ❌ Bad: "I have written down the 5 steps needed to install PostgreSQL."
• 🟢 Good: "5-step PostgreSQL 16 installation and replication setup guide."

3. Strict RequestFeedback Governance

Set RequestFeedback: true only for executable plans (implementation_plan.md) requiring explicit user approval before execution. For reference guides or walk-through notes, set RequestFeedback: false.

Production Tool Call Metadata Examples

Example 1: Implementation Plan Artifact

{
  "TargetFile": "implementation_plan.md",
  "ArtifactMetadata": {
    "Summary": "Implementation Plan: Refactor JWT auth middleware to support Redis blocklist and session revocation.",
    "UserFacing": true,
    "RequestFeedback": true
  }
}

Example 2: Post-Task Walkthrough Artifact

{
  "TargetFile": "walkthrough.md",
  "ArtifactMetadata": {
    "Summary": "Walkthrough: Verified Redis session revocation with 14 unit and integration tests passing.",
    "UserFacing": true,
    "RequestFeedback": false
  }
}

Benchmark Comparison

Evaluation across 30 artifact creation and mutation turns:

Agent Operational Directive

MANDATORY: In ArtifactMetadata.Summary, agents must provide a single concise 1-to-2 sentence summary of document contents. Eliminate all phrases like "This artifact provides..." and set RequestFeedback: true only when user approval is required to proceed.