This is a read-only MCP governance server for the Seshat BI system that lets you inspect and navigate the seven-stage readiness pipeline without executing changes, granting approvals, or connecting to a database. It provides six tools:
seshat_get_status: Report the current readiness stage, evidence, and blockers for all tables or a specific table.
seshat_get_next_action: Determine the single permitted next step for a table based on its readiness, and optionally check if a requested action is allowed.
seshat_explain_blockers: Detail the reasons why a table is blocked from advancing, including missing evidence, owner, and recovery actions.
seshat_prepare_approval_request: Draft a formal approval request for a human decision, providing context and required authority without granting approval itself.
seshat_run_static_check: Run static governance rules against committed artifacts (SQL, TMDL, PBIR) without a database, returning findings and noting live validation was not performed.
seshat_export_evidence_pack: Assemble and return a table's collected readiness evidence as structured data in memory, without writing to disk.
All tools are read-only, idempotent, and keep human judgment in control.
Provides optional dbt adapters for governed extension packs, allowing integration with dbt transformation workflows while remaining advisory and not altering readiness state.
Enables live data validation, drift checks, and statistical evidence generation against a PostgreSQL warehouse as the governed data boundary.
An agent-first readiness system that profiles sources, governs mappings, validates the medallion warehouse, binds metrics to contracts, and prepares Power BI delivery without skipping the human decisions that make analytics trustworthy.
Run the demo · Start contributing · Sponsor a roadmap lane
A dashboard can look finished while its metrics are undefined, its source assumptions are unsafe, and its totals have never been reconciled. Seshat BI makes those gaps visible before they become executive decisions.
It answers one question:
Is this retail source ready to become trusted Power BI?
The answer is never a made-up score. Readiness is recorded as
status + evidence + blocking_reasons, with named human approvals for judgment
calls such as grain, PII, business rollups, and publish safety.
Named for the ancient Egyptian figure of writing, measurement, and record keeping, Seshat brings the same discipline to modern analytics: map meaning, record evidence, then build.
Related MCP server: kafka-sentinel-mcp
Each stage can begin only after the prior stage passes. The sequence is the product.
flowchart LR
S1[1. Source] --> S2[2. Mapping] --> S3[3. Silver] --> S4[4. Gold]
S4 --> S5[5. Semantic Model] --> S6[6. Dashboard] --> S7[7. Publish]
classDef stage fill:#001E35,stroke:#C69214,stroke-width:1.5px,color:#F7F1E7;
class S1,S2,S3,S4,S5,S6,S7 stage;Before Seshat allows... | The evidence must show... |
Silver transformation | Mapping Ready passed and the source map is cleared. |
Power BI over gold | Live validation passed against the real data boundary. |
Dashboard design | Metric contracts exist and define business meaning. |
Power BI execution | Semantic Model Ready and the publish gates passed. |
Seshat never self-grants an approval, invents source meaning, or turns a green static check into a claim of live semantic correctness.
Try the bundled synthetic retail fixture. It needs no database and no Power BI Desktop:
pipx install seshat-bi
seshat demo init
seshat demo run
seshat demo report --format html
The self-contained report shows evidence, blockers, approvals, and the next allowed action across all seven stages. Offline proof stops honestly at Gold Ready; advancing farther requires a live database boundary and governed downstream artifacts.
Principle | What it changes |
Evidence over scores | Every pass cites evidence; every block names a concrete reason. |
Human judgment stays human | Agents surface decisions but cannot approve grain, PII, rollups, or publication. |
Safe sequencing by construction | The agent reads readiness state and performs only the next allowed action. |
Power BI consumes governed truth | Reports read |
Statistics remain derived evidence |
|
This makes Seshat useful to BI developers, analytics engineers, data engineers, analytics leaders, and teams building agents that must stay truthful around real business data.
flowchart LR
RAW([Retail source]) --> B[(bronze)] --> S[(silver)] --> G[(gold)] --> PBI[Power BI PBIP]
MAP{{Source map}} -. clears .-> S
CHECK{{seshat check}} -. static gates .-> S
CHECK -. static gates .-> G
LIVE{{seshat validate}} -. live boundary .-> G
CONTRACT{{Metric contracts}} -. govern measures .-> PBI
HUMAN([Named human approvals]) -. authorize decisions .-> MAP
HUMAN -. authorize publication .-> PBIThe agent is the interface. seshat check and seshat validate are gates the
agent calls; they are helpers, not the product experience.
You want to... | Start here |
Evaluate Seshat in minutes | |
Start a new BI workspace |
|
Adopt an existing PBIP project |
|
Operate Seshat through an agent | |
Make your first contribution |
Seshat BI is an active beta on PyPI -- the PyPI badge above carries the current release. The shipped system includes:
Static and live governance gates over SQL, TMDL/PBIR, DAX, configuration, documentation, keys, date coverage, orphan relationships, and reconciliation.
Seven-stage agent control surfaces through seshat status and seshat next,
grounded in committed evidence rather than a separate run-state engine.
Governed source mapping and metric contracts that stop transformation or dashboard work when business meaning is unresolved.
DAX governance and generation through static rules, contract-drift checks, live value proxies, and verified measure generation.
Portable proof surfaces including offline HTML, review JSON, SARIF, a GitHub Action, readiness passports, and an offline portfolio explorer.
A read-only MCP governor that exposes governance state while refusing execution and approval by construction.
Governed extension packs plus optional dbt and Dagster adapters that remain advisory and never create readiness truth.
Source-controlled Power BI workflows with deterministic PBIR authoring helpers and a read-only assessment path for existing PBIP projects.
Seshat Studio, a local analyst console (seshat-studio, [studio] extra) whose
browser views show workspace readiness, per-table journeys and the agent
conversation over the same committed evidence. Operations, run history and client
review ship as API endpoints without browser views today. Studio surfaces the gates
and never grants an approval of its own.
Explore the capability inventory, release history, and roadmap for the evidence behind each claim.
Power BI writes are gated, not free. The governed local write leg (F016 slice 5,seshat pbi-mcp plan-write / apply) ships and refuses to act without an
approved, in-scope target; the remote leg remains deferred and owner-gated.
Building the final approved page in Power BI Desktop remains a named human
action. See ADR 0018
for what was unparked and what was not.
# core CLI (static checks + the offline demo)
pipx install seshat-bi
seshat init-project my-bi
# to also run the live-data steps (`seshat validate`, `seshat drift`), add the
# optional Postgres driver. Either install it inline:
pipx install "seshat-bi[db]"
# or inject it into an existing pipx install:
pipx inject seshat-bi psycopg2-binary
# governed statistical evidence (exact-pinned numerical environment)
pipx install "seshat-bi[stats]"
seshat analyze --helpThe seshat command is primary. retail is a deprecated compatibility alias kept
for one deprecation cycle. Live database validation needs the optional db extra
(shown above) and a DSN stored only in a gitignored .env. If the driver is
missing, seshat validate / seshat drift print the exact pipx inject /
pip install remedy rather than a raw import error.
The studio extra installs the local analyst console's web stack (FastAPI and
Uvicorn); a base install stays free of them, and seshat-studio reports the
extra's absence as a named diagnostic rather than an import traceback.
The stats extra enables governed descriptive, inference, correlation,
regression, anomaly, and forecast evidence. Change-point detection additionally
uses the stats-change extra. The Gold statistical provider is read-only and
initially PostgreSQL-only; offline local CSV evidence needs no database. See the
architecture boundary and
synthetic workflow.
/plugin marketplace add Kemetra/Seshat-BI
/plugin install seshat-bi@seshat-bi-marketplacecodex plugin marketplace add https://github.com/Kemetra/Seshat-BI
codex plugin add seshat-bi@seshat-bi-repositoryDetailed setup: user install | agent install | support matrix
You do not need to learn the whole readiness system before making a useful first contribution. Seshat provides bounded lanes with owned files, forbidden scope, acceptance evidence, and exact verification commands.
Starter lane | A useful contribution |
KPI contract templates | Clarify reusable business definitions without inventing policy. |
Synthetic fixtures | Add realistic, disclosure-safe test cases. |
Dialect notes | Document compatibility behavior across supported databases. |
Accessibility checks | Improve dashboard and documentation usability. |
Blocker explanations | Make governance findings clearer and more actionable. |
Read the first-contribution guide.
Pick one lane from contribution-lanes.yaml.
Follow the setup and pull-request checks in CONTRIBUTING.md.
Contributions are especially welcome in governance rules, database compatibility, synthetic fixtures, documentation, Power BI artifacts, and agent workflows.
Trusted BI infrastructure is public-interest work: the rules, examples, tests, and documentation should remain inspectable by the teams that depend on them. Sponsorship can accelerate public, evidence-backed roadmap lanes such as:
database compatibility and live-validation evidence,
reproducible demo fixtures and cross-engine coverage,
documentation, onboarding, accessibility, and contributor support,
agent-safety research around analytics approvals and disclosure boundaries.
The guardrail is simple: funding supports the work; it never buys a readiness approval, a rule exception, or an undisclosed product claim.
Sponsor Seshat BI through GitHub Sponsors · Discuss a public roadmap sponsorship
For organization-level sponsorships or roadmap discussions, use the issue link only for non-confidential context. Do not post procurement, client, or payment information in a public issue.
Path | Responsibility |
| Short operating contract and hard stops for agents. |
| Constitution and feature specifications. |
| CLI, governance rules, validation, and agent-facing surfaces. |
| Per-table profiles, source maps, decisions, metrics, and readiness. |
| Tool-agnostic bronze, silver, and gold SQL artifacts. |
| Source-controlled PBIP semantic models and reports. |
| Generic readiness, mapping, metric, dashboard, and handoff blanks. |
| Canonical BI reasoning and workflow knowledge. |
| Architecture, readiness, operations, guides, and worked examples. |
| Unit, integration, contract, and optional live-database evidence. |
Topic | Guide |
Readiness model | |
Architecture | |
Agent operation | |
Existing PBIP adoption | |
Governance vocabulary | |
Frequently asked questions | |
Product direction | |
Release history | |
Brand system |
Seshat BI is a governed Retail BI factory, not a one-click dashboard generator, a Fabric deployment platform, a universal ERP connector, or an automated approval engine. New automation is valuable only when it strengthens one readiness stage without taking a decision away from its accountable human owner.
Seshat BI is available under the Apache License 2.0.
Governed knowledge. Measured structure. Trusted BI.
Seshat BI -- built in public for analytics people who would rather stop a bad number than decorate it.
Explain what blocks one table's next stage, and who can clear it.
Use when: a table is not advancing and you need the concrete reason, the missing evidence, the owner, and the recovery action. Not for: an all-table overview (use seshat_get_status) or picking the next step (use seshat_get_next_action). Returns: one entry per blocker for the named table. Outcome is 'blocked' when blockers exist and 'ok' when none do. Read-only: reports blockers and never clears, waives or overrides one.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\' or '..'. | |
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond annotations: 'Read-only: reports blockers and never clears, waives or overrides one.' It also explains the return format ('one entry per blocker... Outcome is 'blocked'...'). This complements the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, when to use, when not to use, return format, and safety note. Every sentence is purposeful and front-loaded, with no filler. Despite multiple paragraphs, each clause provides distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a diagnostic read operation with no side effects; the description covers purpose, usage, output format, and limitations. With output schema present and safety annotations provided, this is fully complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters documented), so baseline is 3. The description adds no extra parameter-level detail beyond the schema; it only refers to 'one table' and 'named table,' which is already implied. No additional syntax or format info is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Explain what blocks one table's next stage, and who can clear it.' The verb 'explain' and resource 'blockers' are specific, and the 'Not for' section explicitly differentiates from sibling tools (seshat_get_status, seshat_get_next_action), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit: 'Use when: a table is not advancing...' and 'Not for: an all-table overview (use seshat_get_status) or picking the next step (use seshat_get_next_action).' This provides clear context and names alternatives, which is ideal for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assemble one table's evidence pack in memory and return it as data.
Use when: you need a table's collected readiness evidence to review or hand off, as a structured response rather than a file. Not for: writing the pack to disk -- despite the name nothing is exported, and file export stays an explicit CLI operation. Returns: the evidence-pack projection for the named table with any blockers. Outcome is 'input_defect' when the table cannot be resolved. Read-only: creates nothing on disk.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\' or '..'. | |
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only behavior ('Read-only: creates nothing on disk'), corrects the misleading name, and explains the return projection and the 'input_defect' outcome. This goes beyond the annotations by adding functional context and edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the core action, and uses explicit labeled sections (Use when, Not for, Returns, Read-only). Every sentence adds value and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two params, a high-coverage schema, and an output schema present, the description covers the essential context: purpose, exclusions, return value, error outcome, and safety. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add significant param-specific detail beyond what the schema already provides; it only references 'the named table' without elaborating on parameter formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Assemble one table's evidence pack in memory and return it as data.' It explicitly distinguishes itself from file export ('despite the name nothing is exported') and from sibling tools by focusing on in-memory assembly for review or handoff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Not for' conditions: use for reviewing/handing off evidence as structured data, not for writing to disk. This clearly signals when to choose this tool over a CLI-based file export, and the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the one action readiness allows now, and refuse anything past it.
Use when: you need the single permitted next step, or want to check an intended action is allowed before starting it. Not for: the full stage picture (use seshat_get_status) or blocker detail (use seshat_explain_blockers). Returns: one allowed action plus forbidden scope, the stop point and the authority required to go further. Outcome is 'blocked' when requested_scope is forbidden or a named-human decision is outstanding. Read-only: names the action but never performs it, and grants no approval.
| Name | Required | Description | Default |
|---|---|---|---|
| table | No | Single table to scope the answer to, matching a table name or its mapping directory (for example 'retail_store_sales'). Omit to cover every onboarded table in the workspace. May not contain '/', '\' or '..'. | |
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. | |
| requested_scope | No | Plain-text action you intend to take, checked against what readiness currently forbids; words longer than three characters are matched, and a collision returns outcome 'blocked' instead of an allowed action. Omit to simply read the allowed action. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only: names the action but never performs it, and grants no approval,' adding context beyond the readOnlyHint and idempotentHint annotations. It also reveals the 'blocked' outcome condition, which is useful behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections (Use when, Not for, Returns, Read-only) and every sentence provides distinct value. It is appropriately sized with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description still provides key behavioral details, return format, and exclusions. It covers the tool's purpose, usage, limitations, and side effects (none), making it fully complete for an agent to decide when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all parameters, including detailed semantics for requested_scope. The description adds the high-level use case of checking an intended action but no parameter-specific details beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return the one action readiness allows now, and refuse anything past it,' which is a specific verb+resource statement that clearly conveys the tool's function. It also distinguishes from siblings by naming seshat_get_status and seshat_explain_blockers as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a 'Use when' section and a 'Not for' section with named sibling tools, giving clear guidance on when to use this tool versus alternatives. It also mentions checking an intended action, which is a key use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which readiness stage each table currently sits in.
Use when: you need the overall readiness picture, or one table's stage, evidence and blocker list. Not for: why a stage is blocked (use seshat_explain_blockers) or what may be done next (use seshat_get_next_action). Returns: a projection listing each table with its current stage of the seven (source_ready .. publish_ready), evidence and blockers. Outcome is 'ok' unless an input is malformed. Read-only: reads committed files under the workspace and writes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| table | No | Single table to scope the answer to, matching a table name or its mapping directory (for example 'retail_store_sales'). Omit to cover every onboarded table in the workspace. May not contain '/', '\' or '..'. | |
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'reads committed files under the workspace and writes nothing,' adding the specific data source. It also discloses the outcome contract ('Outcome is ok unless an input is malformed') and the return projection, going beyond mere annotation repetition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core function, then structured into 'Use when', 'Not for', 'Returns', and 'Outcome' sections. Each sentence contributes a distinct piece of actionable information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has simple inputs (2 params), a rich output schema, and strong annotations; the description covers the reading behavior, return shape, and outcome semantics. Sibling exclusions and usage context are addressed, leaving no major gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with detailed descriptions for both parameters (workspace path constraint, table constraints including directory matching and forbidden characters). The description adds little new parameter detail, but it does clarify scope semantics ('one table's stage' vs 'overall readiness picture'), consistent with the schema. Therefore baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action ('Report which readiness stage each table currently sits in'), naming the resource (readiness stages per table) and the scope (each table). It differentiates from siblings by naming 'seshat_explain_blockers' and 'seshat_get_next_action' as distinct tools, making the primary purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit 'Use when' and 'Not for' conditions, including named alternative tools for related but different queries. This leaves no doubt about when to select this tool versus its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draft the request a named human must rule on, approving nothing.
Use when: readiness needs a human ruling and you want the request assembled with its supporting issue and the authority required. Not for: granting, recording or standing in for an approval -- no tool here can do that, and a human signs off outside this server. Returns: a request with status 'prepared_not_approved', the requested authority and the supporting issue. Outcome is always 'blocked', by design, because preparing a request advances nothing. Read-only: writes no approval receipt and grants no readiness.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\' or '..'. | |
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. | |
| decision_id | Yes | Caller's identifier for the decision this request covers, recorded verbatim in the prepared request. Must be non-empty text. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations: it explains the return status 'prepared_not_approved', states that the outcome is always 'blocked' by design, and clarifies that it writes no approval receipt and grants no readiness. These details align with the readOnly/idempotent annotations but provide richer context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Use when', 'Not for', 'Returns', and 'Outcome' sections, and every sentence carries useful information without redundancy. It is concise while being thorough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers when to use, what it returns, and its side-effect-free behavior. With an output schema present, it fully equips the agent to decide when to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with descriptions, and the schema description coverage is 100%, so the baseline is 3. The description does not add further parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Draft the request a named human must rule on, approving nothing,' which states a specific verb and resource and clearly distinguishes this tool from approval actions. It is obviously different from sibling tools that query status or run checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: 'Use when: readiness needs a human ruling...' and 'Not for: granting, recording or standing in for an approval.' It also notes that no tool in the set can perform approval, thereby covering alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the static governance rules and state what was not checked.
Use when: you want committed SQL, TMDL, PBIR and readiness artifacts checked against the shipped rule set without any database. Not for: live data validation -- that needs a database connection and stays a separate CLI operation this server never performs. Returns: the findings, plus a boundary object recording that live_validation was 'not_run' and that semantic correctness is not claimed. Outcome is 'blocked' when any finding is error severity. Read-only: opens no database connection and writes no file.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace | Yes | Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses concrete behavioral details: it opens no database connection, writes no file, returns a boundary object recording live_validation as 'not_run', does not claim semantic correctness, and sets outcome to 'blocked' on error severity. This significantly enriches the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line action, followed by clear use-cases, return behavior, and read-only note. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, an output schema, and a clear explanation of return values (findings plus boundary object) and outcome semantics, the description provides a complete picture for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage for the single parameter 'workspace' is 100% with a clear description including path resolution and refusal constraints. The tool description adds no extra parameter semantics, so it rightfully relies on the schema; the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Run the static governance rules and state what was not checked.' This clearly distinguishes it from siblings like seshat_get_status or seshat_export_evidence_pack by focusing on rule execution and explicit scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains explicit 'Use when' and 'Not for' sections, specifying when to use the tool (committed SQL/TMDL/PBIR/readiness artifacts without a database) and excluding live data validation, pointing to a separate CLI operation. This fully addresses when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1seshat_explain_blockers2 fields changedInput schema / properties / table / descriptionAdded value: +"The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\\' or '..'."Input schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."seshat_export_evidence_pack2 fields changedInput schema / properties / table / descriptionAdded value: +"The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\\' or '..'."Input schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."seshat_get_next_action3 fields changedInput schema / properties / requested_scope / descriptionAdded value: +"Plain-text action you intend to take, checked against what readiness currently forbids; words longer than three characters are matched, and a collision returns outcome 'blocked' instead of an allowed action. Omit to simply read the allowed action."Input schema / properties / table / descriptionAdded value: +"Single table to scope the answer to, matching a table name or its mapping directory (for example 'retail_store_sales'). Omit to cover every onboarded table in the workspace. May not contain '/', '\\' or '..'."Input schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."seshat_get_status2 fields changedInput schema / properties / table / descriptionAdded value: +"Single table to scope the answer to, matching a table name or its mapping directory (for example 'retail_store_sales'). Omit to cover every onboarded table in the workspace. May not contain '/', '\\' or '..'."Input schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."seshat_prepare_approval_request3 fields changedInput schema / properties / decision_id / descriptionAdded value: +"Caller's identifier for the decision this request covers, recorded verbatim in the prepared request. Must be non-empty text."Input schema / properties / table / descriptionAdded value: +"The one table to report on, matching a table name or its mapping directory (for example 'retail_store_sales'). Required. May not contain '/', '\\' or '..'."Input schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."seshat_run_static_check1 field changedInput schema / properties / workspace / descriptionAdded value: +"Path to the local Seshat BI workspace to read. Must resolve to exactly the root this server was started with; a parent or subdirectory is refused."v1.0.0seshat_explain_blockersseshat_export_evidence_packseshat_get_next_actionseshat_get_statusseshat_prepare_approval_requestseshat_run_static_checkScored across 6 tools
Each tool targets a distinct aspect of readiness: overall status, next action, blockers, evidence pack assembly, approval request preparation, and static checks. The descriptions explicitly cross-reference each other and clarify 'not for' cases, making misselection unlikely.
All six tools follow a consistent pattern: 'seshat_' prefix plus a verb_noun combination (get_status, get_next_action, explain_blockers, export_evidence_pack, prepare_approval_request, run_static_check). Naming is uniform and predictable.
Six tools is well-scoped for the server's purpose. Each tool covers a distinct operation within readiness governance, and none feel redundant or superfluous.
The tool set comprehensively covers the read-only readiness governance domain: status, next step, blockers, evidence export, approval preparation, and static checks. It intentionally avoids write operations, but for its stated scope (reports and preparation only) there are no obvious gaps.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only MCP for identity resolution and write guardrails.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
