contradiction-mcp

contradiction.sources.sync

Idempotent

Sync local files, website URLs, or GitHub repos to extract factual claims with provenance and trigger automatic contradiction discovery.

Instructions

Ingests and synchronizes one or more external data sources (local document file, public website URL, or GitHub repository), extracts factual claims with exact line provenance, idempotently updates SQLite storage, and triggers automatic contradiction discovery. Mutating and idempotent operation. Supports single source ingestion or concurrent batch synchronization.

Input Schema

TableJSON Schema

Name	Required	Description
`batch`	No	Optional batch array of source requests to synchronize concurrently with failure isolation
`input`	No	Structured connector input object (e.g. { filePath: "..." }) for flexible invocation
`scope`	No	Scope of the document or claims (e.g. "system", "component", "file")
`branch`	No	Optional branch or tag name when syncing GitHub repositories
`source`	No	Source locator: absolute/relative file path for document, public URL for website, or "owner/repo" for GitHub
`subject`	No	Subject entity name for extracted claims (defaults to filename or repository name)
`connector`	Yes	The external source connector to synchronize (document for local files, website for URLs, github for repositories)
`sourceName`	No	Optional human-readable friendly label for the source
`sourceRole`	No	Role of the source in system architecture (e.g. "specification", "configuration", "documentation", "deployment")
`environment`	No	Target environment context for extracted claims (e.g. "production", "staging", "development")
`runDiscovery`	No	Whether to automatically trigger incremental contradiction discovery on touched claims after sync (default: true)

Output Schema

TableJSON Schema

Name	Required	Description
`status`	No	Status of synchronization
`connector`	No	Connector used for sync
`durationMs`	No	Sync execution duration in milliseconds
`repository`	No	Source name or repository synced
`claimsCreated`	No	Number of new claims created
`claimsUpdated`	No	Number of existing claims updated

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.3Sep 18, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint false, idempotentHint true, and openWorldHint true. The description adds beyond annotations by noting it triggers automatic contradiction discovery, supports concurrent batch with failure isolation, and extracts claims with exact line provenance. It repeats 'idempotent' but this is consistent with annotations. No contradiction.

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?

The description is three sentences and front-loaded with the main purpose. However, the second sentence 'Mutating and idempotent operation' is redundant with the annotations and does not earn its place given the rule against repeating structured data. Still compact and well-structured.

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?

The tool is complex with 11 parameters and nested objects, but the schema and output schema fill most gaps. The description covers overall behavior, external source types, batch capability, and side effects. It does not discuss return format, but an output schema exists, so that is not required. Complete enough for correct invocation.

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

Parameters3/5

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

Schema description coverage is 100%, so all 11 parameters are already documented. The description reinforces connector types (document, website, github) and batch mode, but does not add meaning beyond what the schema provides. Baseline 3 is appropriate.

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?

The description states a specific verb and resource: ingests and synchronizes external data sources, extracts factual claims with exact line provenance, updates SQLite storage, and triggers contradiction discovery. This clearly distinguishes it from siblings like sources.test (testing) and conflicts.scan (scanning) by focusing on ingestion and synchronization.

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

Usage Guidelines4/5

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

The description provides clear context that this tool is for ingesting/synchronizing external sources, including single and concurrent batch modes. However, it does not explicitly state when not to use it or name alternative tools like sources.test or sources.list, so no exclusions are provided. The context is clear but lacks explicit comparison to siblings.

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

Deploy Server