biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

Check a translation for structural drift and staleness

check_translation_drift

Compare a translated artifact with its source to detect structural drift and stale timestamps, returning a read-only structured report.

Instructions

Read-only. Compare a translated language variant with its source document (the 'en' source by default) and report both drift kinds in one structured, non-raising TranslationDriftResult. type is one of req, uc, tsk, qa, prb, gol, rsk, dec, sop, vcr, sysrs, txt (feat and adr documents are always English and are rejected with a ValueError); id the artifact's id (shared by both languages); language the translated variant (never 'en'); source_language (default 'en') the language compared against. STRUCTURAL drift: every section heading of both documents is mapped back to canonical English through the language's heading table (the free text of Option N:/Step N:/Extension N./AC-NNN (Method): headings is ignored, only the schema-constant token is compared; timestamp-led update entries are not compared) and structural lists each missing (a source section the variant lacks), extra (a variant section the source lacks) and reordered section with its canonical heading, path, level and positions; a document that fails to parse is an unparseable finding carrying the parse error (byte-identical to list_'s failure text), never raised. STALENESS: stale is true iff the source's frontmatter updated is strictly newer than the variant's (compared as offset-aware datetimes; equal is not stale), with both timestamps, the signed source_ahead_by_seconds, and staleness_error when a timestamp is missing or unparseable. in_sync is true iff there is no structural finding, the variant is not stale and staleness could be determined. Wording, prose, frontmatter values and prb's English problem_statement are never compared. A source or variant that does not exist at all raises the domain's not-found error; invalid type/id/language (path-injection, wrong shape, a language without a heading table, language 'en', equal languages) is a ValueError raised before any file access. It writes, creates and invalidates nothing; to translate or update a variant use the translate_artifact prompt.

Input Schema

Name	Required	Default
`id`	Yes
`type`	Yes
`language`	Yes
`source_language`	No	en

Output Schema

Name	Required	Description	Default
`id`	Yes
`type`	Yes
`stale`	Yes
`in_sync`	Yes
`language`	Yes
`structural`	Yes
`source_path`	Yes
`variant_path`	Yes
`source_updated`	Yes
`source_language`	Yes
`staleness_error`	Yes
`variant_updated`	Yes
`source_ahead_by_seconds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.38.0Nov 2, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so: read-only and writes nothing, parse failures surfaced as non-raising 'unparseable' findings, not-found errors raised, ValueErrors raised before any file access, and strict-vs-equal staleness semantics with offset-aware datetimes. It also enumerates what is deliberately not compared.

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 read-only statement and the core action, and every clause carries substantive information. The density is high, though — a long semicolon-chained paragraph covering schema tokens, timestamp comparison and error modes would scan better with light structure.

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

Completeness5/5

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

For a tool with four parameters, no annotations and an output schema, the description covers input constraints, comparison rules, error behavior and the shape of the result categories. An agent has everything needed to call it correctly and interpret failure modes.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate and does: it explains that type is one of twelve enumerated artifacts (with feat/adr excluded), id is shared across languages, language must never be 'en', and source_language defaults to 'en' and is what the variant is compared against.

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?

Opens with a specific verb and resource: compare a translated language variant with its source document and report structural drift and staleness. No sibling tool performs translation-drift checking, and the description makes the scope unambiguous, including that it is read-only.

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?

It clearly routes mutation intent elsewhere ('to translate or update a variant use the translate_artifact prompt') and states which document types are rejected (feat and adr) plus the invalid-input conditions. It stops short of an explicit 'use this when you suspect a variant is out of date' framing, but the context is clear.

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

Deploy Server