s2docs MCP Server

Overview Schema Source Related Servers Discussions Admin

add_evidence

Records structured evidence for a project step so its evidence gate can be satisfied before marking the step done. Supports console transcripts, hashes, pixel diffs, screenshots, and notes.

Instructions

Record structured evidence for a step. This is what the evidence gate checks — a step with an evidence gate CANNOT be marked done until at least one non-note row exists for it. Use kind='note' only for a supplementary remark (it does not satisfy the gate).

    Pass `step_id` to attach the row to a project step, or omit it to record evidence at project
    level (a measurement, a console transcript, a negative result). A step-less row satisfies no
    step gate, by design.

Input Schema

Name	Required	Description
`ref`	No	Path / url / command the evidence points at
`data`	No	Structured detail: e.g. {'pixel_diff_pct': 1.2, 'noise_floor': 0.5} or {'md5': '...'}
`kind`	Yes
`step_id`	No	Project step the evidence proves (e.g. 'research'). Omit for project-level evidence that is not tied to a step — the column is nullable and the REST route has always accepted null, so MCP must not be stricter than HTTP.
`project_id`	Yes	Project id from start_project, e.g. 'p-1a2b3c4d'

Output Schema

Name	Required	Description
`id`	Yes
`ref`	No	Path / url / command the evidence points at
`data`	No	Structured detail (md5s, pixel diff pct, transcript excerpt)
`kind`	Yes
`step_id`	No	Owning step; None = project-level evidence
`created_at`	Yes
`project_id`	No	Owning project; None when the row is anchored to a test run with no project
`test_run_id`	No	Test run this evidence records (a human-confirm verdict, a transcript, ...)

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 23, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds non-obvious domain behavior: a step with an evidence gate cannot be marked done until a non-note row exists, and a step-less row satisfies no step gate by design. That gate interaction is exactly the context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the gate rule, then parameter-level guidance in short paragraphs. Slightly more prose than strictly needed (the REST-route justification is rationale rather than instruction), but every sentence carries actionable meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation, and the description covers the mutation's downstream effect and the step_id optionality rule. It does not sketch what a valid ref/data pairing looks like per kind, but that is a minor gap for a 5-param create tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, but the description still adds meaning to step_id (omit for project-level evidence, contrast with the REST route accepting null) and to kind (note vs. gate-satisfying kinds). Remaining kinds like pixel_diff and file_hash are only enumerated in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Record structured evidence for a step') and immediately ties it to the evidence gate. An agent can tell this is the write-side counterpart to list_evidence without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use kind='note' (supplementary remark, does not satisfy the gate) and when to omit step_id (project-level evidence such as measurement, console transcript, negative result). Both branches are covered with their consequences.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server