diff --git a/php/Mcp/Tools/Agent/Session/SessionArtifact.php b/php/Mcp/Tools/Agent/Session/SessionArtifact.php
index 9f2b0c9..2df2cff 100644
--- a/php/Mcp/Tools/Agent/Session/SessionArtifact.php
+++ b/php/Mcp/Tools/Agent/Session/SessionArtifact.php
@@ -70,11 +70,10 @@ class SessionArtifact extends AgentTool
             return $this->error('Session not found');
         }
 
-        $session->addArtifact(
-            $path,
-            $action,
-            $this->optional($args, 'description')
-        );
+        $description = $this->optional($args, 'description');
+        $metadata = $description !== null ? ['description' => $description] : null;
+
+        $session->addArtifact($path, $action, $metadata);
 
         return $this->success(['artifact' => $path]);
     }
diff --git a/php/tests/Feature/Mcp/SessionArtifactTest.php b/php/tests/Feature/Mcp/SessionArtifactTest.php
new file mode 100644
index 0000000..b12ad11
--- /dev/null
+++ b/php/tests/Feature/Mcp/SessionArtifactTest.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+use Core\Mod\Agentic\Mcp\Tools\Agent\Session\SessionArtifact;
+use Core\Mod\Agentic\Models\AgentSession;
+
+it('records artifact descriptions as metadata without throwing a type error', function () {
+    $workspace = createWorkspace();
+    $session = AgentSession::start(null, AgentSession::AGENT_OPUS, $workspace);
+    $tool = new SessionArtifact;
+
+    $payload = [
+        'session_id' => $session->session_id,
+        'path' => 'docs/session-artifact.md',
+        'action' => 'modified',
+        'description' => 'some narrative text',
+        'metadata' => null,
+    ];
+
+    $result = null;
+
+    expect(function () use ($tool, $payload, $session, &$result): void {
+        $result = $tool->handle($payload, ['session_id' => $session->session_id]);
+    })->not->toThrow(TypeError::class);
+
+    expect($result)->toBeArray()
+        ->and($result['success'])->toBeTrue()
+        ->and($result['artifact'])->toBe('docs/session-artifact.md');
+
+    $artifacts = $session->fresh()->artifacts;
+
+    expect($artifacts)->toHaveCount(1)
+        ->and($artifacts[0]['path'])->toBe('docs/session-artifact.md')
+        ->and($artifacts[0]['action'])->toBe('modified')
+        ->and($artifacts[0]['metadata'])->toBe(['description' => 'some narrative text']);
+});