A read-only MCP governor for Seshat BI workspaces that exposes readiness state and governance evidence without approving or executing anything.
seshat_get_status – Report each table's current readiness stage (source_ready..publish_ready), evidence, and blockers.
seshat_get_next_action – Return the single allowed next action, forbid anything beyond it, and block if requested scope collides with readiness rules or a named-human decision is outstanding.
seshat_explain_blockers – Explain what blocks one table's next stage, the missing evidence, the owner, and the recovery action.
seshat_prepare_approval_request – Draft an approval request for a named human (status prepared_not_approved), never granting or recording approval.
seshat_run_static_check – Run static governance rules over committed SQL, TMDL, PBIR, and readiness artifacts, reporting findings plus a boundary noting live validation was not run.
seshat_export_evidence_pack – Assemble and return one table's evidence pack in memory as structured data, without writing any file.
All tools are read-only, require a workspace path that resolves to the server root, write nothing, open no database connections, and cannot approve, execute, or override gates.
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.
The readiness system that lets AI agents build your BI pipeline, but never lets them approve it. Seshat profiles sources, governs mappings, validates the medallion warehouse, binds metrics to contracts, and gates Power BI delivery. Every step is backed by committed evidence, and every judgment call by a named human approval.
Try it in 60 seconds · Install · How it works · What's new in 3.0 · Contribute
Run the bundled synthetic retail demo. All you need is uv, which fetches a matching Python if you lack one. You do not need a database, Power BI Desktop, or an account.
uvx --from seshat-bi seshat demo init
uvx --from seshat-bi seshat demo run
uvx --from seshat-bi seshat demo report --format htmlOpen the readiness proof it wrote to .seshat-output/demo/index.html:
start .seshat-output\demo\index.html # Windows
open .seshat-output/demo/index.html # macOS
xdg-open .seshat-output/demo/index.html # LinuxPrefer a persistent install? Run pipx install seshat-bi once, then drop the
uvx --from seshat-bi prefix: seshat demo init, seshat demo run,
seshat demo report --format html. Leave off --format html to print the same report
in the terminal.
The committed demo fixture records three passing stages, each citing its
evidence: the source profile (24 rows, order_id unique), the cleared source
map, and the authored silver migration.
Gold is blocked, on purpose. Its gate is a live seshat validate run against
a real database, and the demo never runs one, so it caps Gold at blocked. Seshat names that reason instead of
pretending the stage passed.
The approvals are labelled. The demo's approvals are marked illustrative fixture, not produced by this run. Seshat never fabricates a sign-off.
One next action. The report names the single step that is allowed next. There is no score to game.
That honest "blocked" is the product. A tool that turns every stage green without a database behind it is guessing.
Related MCP server: kafka-sentinel-mcp
A dashboard can look finished while its metrics are undefined, its source assumptions are unsafe, and its totals have never been reconciled. AI agents make this worse: they produce a plausible-looking model fast, then quietly decide the grain, the PII handling, and what "revenue" means.
Seshat BI answers one question, and it never makes up the answer:
Is this retail source ready to become trusted Power BI?
A typical BI build... | With Seshat BI... |
"Looks done" when the visuals render | Each stage records |
The agent picks the grain and the keys | The agent surfaces the decision; a named human records it |
Measures are written straight into DAX | Measures trace to approved metric contracts; drift is flagged |
Totals are eyeballed in the report | Keys, date coverage, orphan relationships and reconciliation are checked against the live warehouse |
A readiness score of "87%" | No score. Every pass cites evidence and every block names a reason |
Publishing is a button | Publishing is the last of seven gates, and a human owns it |
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.
A stage can begin only after the stage before it 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;Source -> Mapping -> Silver -> Gold -> Semantic Model -> Dashboard -> Publish
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.
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 .-> PBIData flows from the retail source through bronze, silver, and gold into a
source-controlled Power BI PBIP project. Four kinds of gate sit along that path:
a source map that must be cleared before silver,
seshat check, which runs static gates over silver and gold,
seshat validate, which checks gold against the live database, and
metric contracts, which govern every Power BI measure.
Named human approvals authorize the mapping decisions and the publication.
The agent is the interface. You work through Claude Code, Codex, or the local Studio
console. seshat status tells the agent where each table stands, seshat next gives
it the one allowed next action, and seshat check / seshat validate are the gates
it must pass. The CLI is the engine, not the experience.
You want to... | Start here |
See it work in a minute | |
Start a new BI workspace |
|
Find out what to do next |
|
Adopt an existing PBIP project (read-only) |
|
Gate a pull request |
|
Operate Seshat through an agent | |
Make your first contribution |
v3.0.0 is a major release, and the reason matters: it adds very little and tightens a lot. An expert-board audit closed places where a gate could pass on an absent, uncommitted, or unparseable input. Those gates now refuse.
Approvals must be committed. Approval-bearing surfaces read HEAD, not the
working tree, and a stage's approval must come from that stage's authority.
Stricter secret scanning. C2 now also flags tracked .env.local-style files,
filled *_TOKEN / *_SECRET keys in .env.example, and DSNs in UTF-16 files.
Safer resets and git reads. seshat reset refuses to delete uncommitted work
unless --discard-uncommitted is passed, and git reads refuse reflog revisions.
dbt and Dagster gates read committed state. A zero-asset run no longer counts as success.
New opt-in and additive surfaces. seshat next --exit-code, extra
seshat doctor --format json keys, and table-scoped Studio conversations.
No rule id was added, removed, or renamed. Upgrading from 2.x? Read the v3.0 release note and migration table first: a repo that was green on v2.1 can turn red, and that is deliberate.
Seshat BI is an active beta on PyPI. The PyPI badge above shows 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 while business meaning is unresolved, including governed two-table ratios.
DAX governance and generation through static rules, contract-drift checks, live value proxies, and verified measure generation.
Governed statistical evidence. seshat analyze runs a closed catalog of
governed methods over approved metrics, then stops for named-human review without
changing readiness.
Portable proof surfaces: offline HTML, review JSON, SARIF, a GitHub Action, readiness passports, and an offline portfolio explorer.
A read-only MCP governor (seshat mcp, [mcp] extra) that exposes
governance state to local MCP clients over stdio and refuses execution and
approval by construction. It is listed in
Awesome MCP Servers and
scored on Glama.
Governed extension packs, plus optional dbt and Dagster adapters that stay 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).
Its 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 with no browser views yet. Studio surfaces the gates
and never grants an approval of its own.
The capability inventory, release history, and roadmap hold 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, readiness status, and the offline demo
pipx install seshat-bi
# ...or run any command without installing
uvx --from seshat-bi seshat --version
# Start a governed workspace
seshat init-project my-biThe base install depends only on PyYAML. Everything heavier is an opt-in extra:
Extra | Adds | Install |
| Live PostgreSQL validation ( |
|
| Live validation on SQL Server, MySQL, or Snowflake |
|
| Governed statistical evidence ( |
|
| Change-point detection on top of |
|
| The governed dbt transformation adapter |
|
| Excel source profiling (CSV needs no extra) |
|
| HTML and Excel reports / PDF rendering |
|
| The local stdio read-only MCP governor |
|
| The Seshat Studio web console (FastAPI + Uvicorn) |
|
Already installed? Add an extra's packages in place, for example
pipx inject seshat-bi psycopg2-binary for db.
Live validation reads a DSN stored only in a gitignored .env. Copy
.env.example to
.env and fill in your own values. If the database driver or the mcp, dbt, or
studio extra is missing, Seshat prints the exact pipx inject / pip install fix
instead of an import traceback.
seshat is the primary command. retail is a deprecated alias, kept for one
deprecation cycle.
The statistical provider is read-only and initially PostgreSQL-only. Offline local CSV evidence needs no database. See the architecture boundary and the synthetic workflow.
Claude Code
/plugin marketplace add Kemetra/Seshat-BI
/plugin install seshat-bi@seshat-bi-marketplaceCodex
codex plugin marketplace add https://github.com/Kemetra/Seshat-BI
codex plugin add seshat-bi@seshat-bi-repositoryDetailed setup: user install | agent install | support matrix
BI developers who want Power BI models that trace back to governed gold tables.
Analytics engineers and data engineers running a bronze -> silver -> gold warehouse who need gates that fail closed.
Analytics leaders who need to know which numbers are safe to put in front of executives, and who approved them.
Teams building AI agents that must stay truthful around real business data.
You don't need to learn the whole readiness system before making a useful first contribution. Seshat provides bounded lanes, each 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 stay inspectable by the teams that depend on them. Sponsorship can speed up 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 | |
Demo internals | |
Governance vocabulary | |
Frequently asked questions | |
Product direction | |
Release history | |
Brand system |
Seshat BI is a governed Retail BI factory. It is 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.
If Seshat BI stopped a bad number before it reached a meeting, or you think it should, star the repo. ⭐ It is the simplest way to help other analytics teams find it.
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 for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
